Getting Started

First Steps

Installation

composer require kainxspirits/laravel-pubsub-queue:^0.10.0

Publish the config file:

php artisan vendor:publish --provider="KainXSpirits\PubSubQueue\PubSubQueueServiceProvider" --tag="pubsub-queue-config"

Configure .env Add Google Cloud credentials and project ID:

PUBSUB_QUEUE_CONNECTION=google-pubsub
PUBSUB_PROJECT_ID=your-project-id
PUBSUB_KEY_FILE=/path/to/service-account-key.json

Set Up Queue Connection In config/queue.php, ensure the connections array includes:

'google-pubsub' => [
    'driver' => 'google-pubsub',
    'project_id' => env('PUBSUB_PROJECT_ID'),
    'key_file' => env('PUBSUB_KEY_FILE'),
    'subscription' => env('PUBSUB_SUBSCRIPTION_NAME', 'default-subscription'),
    'topic' => env('PUBSUB_TOPIC_NAME', 'default-topic'),
],

Dispatch a Job

use App\Jobs\ProcessOrder;

ProcessOrder::dispatch($order)->onQueue('google-pubsub');

First Use Case: Basic Job Processing

Define a Job (Laravel 12 compatible):

namespace App\Jobs;

use Illuminate\Bus\Queueable;
use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Foundation\Bus\Dispatchable;
use Illuminate\Queue\InteractsWithQueue;

class ProcessOrder implements ShouldQueue
{
    use Dispatchable, InteractsWithQueue, Queueable;

    public function handle()
    {
        // Your logic here
    }
}

Run the Worker:

php artisan queue:work --queue=google-pubsub

Implementation Patterns

Workflow: Pub/Sub Integration

Topic-Based Routing Use different topics for different job types (e.g., orders, notifications):

ProcessOrder::dispatch()->onQueue('google-pubsub:orders');

Configure in config/queue.php:

'google-pubsub:orders' => [
    'driver' => 'google-pubsub',
    'topic' => 'orders-topic',
],

Subscription Management

Create subscriptions for specific queues:

php artisan pubsub:subscribe orders-topic orders-subscription

Monitor subscriptions via Google Cloud Console or CLI:

gcloud pubsub subscriptions list --project=your-project-id

Batch Processing Leverage Pub/Sub’s batching for high-throughput queues:

// In your job's handle() method
if ($this->batchSize >= 100) {
    // Process batch
}

Integration Tips

Dead Letter Queues (DLQ) Configure a DLQ subscription for failed jobs:

'google-pubsub' => [
    'driver' => 'google-pubsub',
    'dead_letter_subscription' => 'failed-jobs-dlq',
],

Retry Logic Use Laravel’s built-in retry mechanism with exponential backoff:
```
public function retryUntil()
{
    return now()->addMinutes(5);
}
```
Monitoring Integrate with Laravel Horizon for real-time monitoring:
```
php artisan horizon
```

New Feature: Push() After Commit

With v0.10.0, the push() method now works correctly after afterCommit() in transactions:

DB::transaction(function () {
    // Your database operations
    ProcessOrder::dispatch($order)->afterCommit();
});

Gotchas and Tips

Pitfalls

Authentication Issues
- Ensure PUBSUB_KEY_FILE points to a valid service account JSON key.
- Verify the service account has roles/pubsub.editor and roles/pubsub.subscriber permissions.
Subscription Mismatch
- If jobs aren’t processing, check that the subscription exists and matches the topic in the queue config.
- Run:
```
gcloud pubsub subscriptions describe orders-subscription --project=your-project-id
```
Message Size Limits
- Pub/Sub has a 10MB message limit. For larger payloads, use external storage (e.g., GCS) and pass a reference in the job.
Worker Stuck on Acknowledgment
- If a worker crashes, unacknowledged messages will retry. To manually acknowledge:
```
gcloud pubsub subscriptions pull orders-subscription --auto-ack=false
```

Debugging

Log Messages Enable debug logging in config/pubsub-queue.php:
```
'debug' => env('PUBSUB_DEBUG', false),
```

Check Worker Logs Run the worker with verbose output:

php artisan queue:work --queue=google-pubsub --verbose

Test Locally Use the google-pubsub driver with a local emulator (e.g., Google Cloud Emulator) for development.

Extension Points

Custom Message Attributes Attach metadata to jobs:

ProcessOrder::dispatch($order)
    ->onQueue('google-pubsub')
    ->withChain([
        new AddPubSubAttributes(['priority' => 'high']),
    ]);

Middleware for Pre/Post Processing Extend the queue driver with middleware:

namespace App\Queue;

use Illuminate\Contracts\Queue\Middleware;

class LogJobMiddleware implements Middleware
{
    public function handle($job, $next)
    {
        \Log::info('Job dispatched: ' . $job->getJob());
        return $next($job);
    }
}

Queue::addMiddleware(LogJobMiddleware::class);

Event Listeners for Pub/Sub Events Listen to Pub/Sub events (e.g., message published/submitted):

use KainXSpirits\PubSubQueue\Events\MessagePublished;

MessagePublished::listen(function ($event) {
    \Log::debug('Message published to topic: ' . $event->topic);
});

Config Quirks

Default Subscription/Topic If not specified, the package uses default-subscription and default-topic. Override in .env:
```
PUBSUB_SUBSCRIPTION_NAME=custom-sub
PUBSUB_TOPIC_NAME=custom-topic
```

Environment-Specific Config Use config/queue.php to define environment-specific connections:

'connections' => [
    'google-pubsub' => [
        'driver' => 'google-pubsub',
        'topic' => env('PUBSUB_TOPIC_NAME', config('pubsub.default_topic')),
    ],
],

Laravel 12 Compatibility

Updated Job Traits The package now fully supports Laravel 12's updated job traits (InteractsWithQueue is now required alongside Queueable).
New Artisan Commands Ensure you're using the latest Artisan commands for Pub/Sub management:
```
php artisan pubsub:subscribe --help
```

Breaking Changes

Transaction Handling If you were relying on previous behavior where push() didn't work after afterCommit(), this has now been fixed. Ensure your transaction logic is updated to leverage this new behavior.

Laravel Pubsub Queue Laravel Package