Creating Queue Jobs

This guide walks you through creating, configuring, and testing asynchronous jobs in Laravel.

Basic Job Creation

Using Artisan

./vendor/bin/sail artisan make:job ProcessPayment

This creates a job class at app/Jobs/ProcessPayment.php:

<?php

namespace App\Jobs;

use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Foundation\Queue\Queueable;

class ProcessPayment implements ShouldQueue
{
    use Queueable;

    public function __construct()
    {
    }

    public function handle(): void
    {
    }
}

Complete Job Structure

<?php

namespace App\Jobs;

use App\Models\Order;
use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Foundation\Queue\Queueable;
use Illuminate\Support\Facades\Log;
use Throwable;

class ProcessOrderPayment implements ShouldQueue
{
    use Queueable;

    public function __construct(
        public Order $order,
        public string $paymentMethod
    ) {}

    public function handle(): void
    {
        Log::info('Processing payment', [
            'order_id' => $this->order->id,
            'method' => $this->paymentMethod,
        ]);

        // Your business logic here
    }

    public function failed(?Throwable $exception): void
    {
        Log::error('Payment processing failed', [
            'order_id' => $this->order->id,
            'error' => $exception?->getMessage(),
        ]);
    }
}

Job Configuration

Retry Configuration

class ProcessPayment implements ShouldQueue
{
    use Queueable;

    public int $tries = 3;
    public int $backoff = 10;
}

Exponential Backoff:

public function backoff(): array
{
    return [10, 30, 60]; // Wait 10s, 30s, then 60s
}

Timeout Configuration

class ProcessPayment implements ShouldQueue
{
    use Queueable;

    public int $timeout = 60; // 1 minute
}

Queue and Connection

class ProcessPayment implements ShouldQueue
{
    use Queueable;

    public string $queue = 'payments';
    public string $connection = 'sqs';
}

Dispatching Jobs

Basic Dispatch

use App\Jobs\ProcessPayment;
use App\Models\Order;

$order = Order::find(1);

ProcessPayment::dispatch($order, 'credit_card');

Delayed Dispatch

ProcessPayment::dispatch($order, 'credit_card')
    ->delay(now()->addMinutes(5));

Custom Queue

ProcessPayment::dispatch($order, 'credit_card')
    ->onQueue('high-priority');

Conditional Dispatch

ProcessPayment::dispatchIf($order->isPaid(), $order, 'credit_card');
ProcessPayment::dispatchUnless($order->isProcessing(), $order, 'credit_card');

Synchronous Dispatch

ProcessPayment::dispatchSync($order, 'credit_card');

After Database Commit

ProcessPayment::dispatch($order, 'credit_card')
    ->afterCommit();

Error Handling

Failed Method

public function failed(?Throwable $exception): void
{
    Log::error('Job failed', [
        'job' => static::class,
        'order_id' => $this->order->id,
        'error' => $exception?->getMessage(),
    ]);

    $this->order->update([
        'status' => 'payment_failed',
        'error_message' => $exception?->getMessage(),
    ]);
}

Failing Explicitly

public function handle(): void
{
    if (!$this->order->isValid()) {
        $this->fail('Order is not valid');
        return;
    }
}

Releasing Back to Queue

public function handle(): void
{
    if (!$this->apiIsAvailable()) {
        $this->release(30); // Retry in 30 seconds
        return;
    }
}

Job Middleware

Rate Limiting

use Illuminate\Queue\Middleware\RateLimited;

public function middleware(): array
{
    return [new RateLimited('payment-api')];
}

Define rate limit in AppServiceProvider:

use Illuminate\Cache\RateLimiting\Limit;
use Illuminate\Support\Facades\RateLimiter;

RateLimiter::for('payment-api', function (object $job) {
    return Limit::perMinute(30);
});

Without Overlapping

use Illuminate\Queue\Middleware\WithoutOverlapping;

public function middleware(): array
{
    return [
        (new WithoutOverlapping($this->order->id))
            ->expireAfter(180)
            ->dontRelease()
    ];
}

Testing Jobs

Using Queue Fake

use App\Jobs\ProcessPayment;
use Illuminate\Support\Facades\Queue;

test('payment job is dispatched', function () {
    Queue::fake();

    $order = Order::factory()->create();
    ProcessPayment::dispatch($order, 'credit_card');

    Queue::assertPushed(ProcessPayment::class, function ($job) use ($order) {
        return $job->order->id === $order->id;
    });
});

Testing Job Logic

test('payment job processes order', function () {
    $order = Order::factory()->create(['status' => 'pending']);

    $job = new ProcessPayment($order, 'credit_card');
    $job->handle();

    expect($order->fresh()->status)->toBe('paid');
});

Testing Failed Jobs

test('payment job logs failure', function () {
    Log::spy();

    $order = Order::factory()->create();
    $job = new ProcessPayment($order, 'credit_card');
    $exception = new \Exception('Payment API unavailable');

    $job->failed($exception);

    Log::shouldHaveReceived('error')->once();
});

Best Practices

1. Keep Jobs Small and Focused

Bad:

class ProcessOrder implements ShouldQueue
{
    public function handle(): void
    {
        // Process payment, send email, update inventory, generate invoice
    }
}

Good:

class ProcessOrderPayment implements ShouldQueue
{
    public function handle(): void
    {
        // Only process payment
    }
}

2. Use Job Chaining

ProcessOrderPayment::withChain([
    new SendOrderConfirmation($order),
    new UpdateInventory($order),
])->dispatch($order);

3. Serialize Minimal Data