Queues en jobs - Knowledge of Laravel

Wat is een queue?

In webapplicaties komen taken voor die meerdere seconden duren, zoals het versturen van e-mails, het verkleinen van afbeeldingen of het aanroepen van externe API’s. Als je dit synchroon binnen een HTTP-request doet, moet de gebruiker wachten totdat de response terugkomt. Met Laravel queues kun je zulke zware taken asynchroon op de achtergrond uitvoeren. De request geeft direct een response terug, terwijl een workerproces de eigenlijke taak apart afhandelt.

Queues ondersteunen meerdere backends, waaronder database, Redis en Amazon SQS. In een ontwikkelomgeving kun je de sync-driver gebruiken om jobs direct uit te voeren zonder queue.

Queue-configuratie

config/queue.php

De queue-configuratie staat gebundeld in config/queue.php. Met de omgevingsvariabele QUEUE_CONNECTION schakel je tussen drivers.

// config/queue.php
'default' => env('QUEUE_CONNECTION', 'database'),

.env instellen

# Driver kiezen
QUEUE_CONNECTION=database

# Bij gebruik van Redis
# QUEUE_CONNECTION=redis
# REDIS_HOST=127.0.0.1
# REDIS_PORT=6379

De databasedriver voorbereiden

Als je de database-driver gebruikt, heb je een tabel nodig om jobs in op te slaan. Nieuwe projecten vanaf Laravel 11 bevatten de migration standaard, maar als die ontbreekt maak je hem aan met de volgende commando’s.

php artisan make:queue-table
php artisan migrate

De Redis-driver voorbereiden

Gebruik je de redis-driver, voeg dan een Redis-verbindingsconfiguratie toe aan config/database.php en installeer de driver via Composer.

composer require predis/predis

SQS Overflow Storage

Amazon SQS heeft een limiet op de maximale grootte van message payloads. Werk je met jobs waarvan de payload groot kan worden, voeg dan een configuratie toe die het overschot in een cache store opslaat en alleen een pointer naar SQS stuurt.

'sqs' => [
    // ...
    'overflow' => [
        'enabled' => env('SQS_OVERFLOW_ENABLED', false),
        'store' => env('SQS_OVERFLOW_STORE'),
        'always' => false,
        'delete_after_processing' => true,
        'flush_on_clear' => env('SQS_OVERFLOW_FLUSH_ON_CLEAR', false),
    ],
],

Als je enabled aanzet, worden payloads van 1 MB of groter opgeslagen in de opgegeven cache store.
Zet je always op true, dan worden alle SQS-payloads ongeacht hun grootte in de cache store opgeslagen.
delete_after_processing verwijdert de opgeslagen payload nadat de job geslaagd is (standaard true).
Zet je flush_on_clear op true, dan wordt bij het uitvoeren van queue:clear een flush gedaan op de overflow-store. Gebruik dit in combinatie met een aparte store, zodat je de reguliere cache niet wist.

Een jobklasse maken

Het make:job commando

Met het Artisan-commando make:job genereer je een sjabloon voor een jobklasse.

php artisan make:job SendWelcomeEmail

Het bestand app/Jobs/SendWelcomeEmail.php wordt gegenereerd.

Structuur van een jobklasse

<?php

namespace App\Jobs;

use App\Models\User;
use App\Mail\WelcomeMail;
use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Foundation\Queue\Queueable;
use Illuminate\Support\Facades\Mail;

class SendWelcomeEmail implements ShouldQueue
{
    use Queueable;

    /**
     * Maak een instantie van de job
     */
    public function __construct(
        public User $user,
    ) {}

    /**
     * Voer de job uit
     */
    public function handle(): void
    {
        Mail::to($this->user->email)->send(new WelcomeMail($this->user));
    }
}

Door de interface ShouldQueue te implementeren laat je Laravel weten dat deze job asynchroon via de queue verwerkt moet worden. De trait Queueable levert de methoden die nodig zijn voor de queue-bewerkingen van de job.

Geef je een Eloquent-model door aan de constructor, dan serialiseert Laravel automatisch alleen het ID. Bij het uitvoeren worden de meest recente gegevens opnieuw uit de database opgehaald, waardoor de queue-payload licht blijft.

Jobs dispatchen

dispatch()

Om een job vanuit een controller of service naar de queue te sturen gebruik je dispatch().

use App\Jobs\SendWelcomeEmail;

// In een route of controller
public function register(Request $request): RedirectResponse
{
    $user = User::create($request->validated());

    // Job op de queue plaatsen
    SendWelcomeEmail::dispatch($user);

    return redirect('/dashboard');
}

Vertraagd dispatchen

Met de methode delay() kun je de uitvoering van een job een opgegeven tijd uitstellen.

// Na 5 minuten uitvoeren
SendWelcomeEmail::dispatch($user)->delay(now()->addMinutes(5));

dispatchAfterResponse()

Met dispatchAfterResponse() wordt de job direct nadat de HTTP-response naar de gebruiker is teruggestuurd uitgevoerd. Dit werkt ook met de sync-driver en is daarom geschikt voor lichte taken waarvoor geen aparte worker nodig is.

SendWelcomeEmail::dispatchAfterResponse($user);

Dispatchen naar een specifieke queue

SendWelcomeEmail::dispatch($user)->onQueue('emails');

Queue Routing

Om een specifieke jobklasse standaard naar een vaste verbinding en queue te routeren, gebruik je Queue::route() in de boot() van een ServiceProvider. Zo beheer je alles centraal in plaats van per jobklasse onQueue() / onConnection() te schrijven.

use App\Concerns\RequiresVideo;
use App\Jobs\ProcessPodcast;
use App\Jobs\ProcessVideo;
use Illuminate\Support\Facades\Queue;

public function boot(): void
{
    Queue::route(ProcessPodcast::class, connection: 'redis', queue: 'podcasts');
    Queue::route(RequiresVideo::class, queue: 'video');
}

Je kunt ook interfaces, traits of parent classes opgeven. De routing wordt dan automatisch toegepast op alle jobs die deze implementeren, gebruiken of erven. Om meerdere jobs in één keer te routeren geef je een array door.

Queue::route([
    ProcessPodcast::class => ['redis', 'podcasts'], // connection en queue
    ProcessVideo::class => 'videos',                // alleen queue (standaardverbinding wordt gebruikt)
]);

Queue Routing kan worden overschreven met onQueue() / onConnection() op de job zelf.

Queues doorsturen (`Queue::forward()`)

Met Queue::forward() kun je jobs van de ene queue doorsturen naar een andere queue of verbinding. Handig als je de queue-infrastructuur wilt wisselen zonder de individuele jobs of de aanroepende code aan te passen.

use Illuminate\Support\Facades\Queue;

Queue::forward('reports', 'reports.fifo', 'sqs');
Queue::forward('payments', connection: 'sqs');
Queue::forward('updates', 'notifications');

Om meerdere queues in één keer door te sturen geef je een array door.

Queue::forward([
    'reports' => 'reports.fifo',
    'emails' => 'emails.fifo',
], connection: 'sqs');

Als de job zelf expliciet een verbinding opgeeft, heeft de instelling van de job voorrang op de doorstuurconfiguratie.

Synchroon uitvoeren (voor testen en ontwikkeling)

Met dispatchSync() voer je een job direct uit zonder de queue te gebruiken.

SendWelcomeEmail::dispatchSync($user);

Bulk dispatchen

Als je een groot aantal onafhankelijke jobs in één keer wilt dispatchen, kun je de methode bulk() van de Bus-facade gebruiken. Ideaal voor gevallen waarin je geen tracking of callbacks zoals bij batchverwerking nodig hebt. Bus::bulk() groepeert jobs op de geconfigureerde queue-verbinding en queuenaam en pusht elke groep in één keer naar de queue, wat efficiënt is.

use App\Jobs\ProcessUser;
use Illuminate\Support\Facades\Bus;

Bus::bulk(
    $users->map(fn ($user) => new ProcessUser($user))
);

Bus::bulk() verstuurt jobs gebundeld naar de queue. Anders dan bij batchverwerking (Bus::batch()) krijg je geen voortgangstracking of voltooiingscallbacks. Het is geschikt als je een grote hoeveelheid onafhankelijke jobs simpelweg in één keer wilt versturen.

Job chains

Door jobs te chainen kun je meerdere jobs na elkaar uitvoeren. Als een job in de chain mislukt, worden de volgende jobs niet uitgevoerd.

use App\Jobs\OptimizePodcast;
use App\Jobs\ProcessPodcast;
use App\Jobs\ReleasePodcast;
use Illuminate\Support\Facades\Bus;

Bus::chain([
    new ProcessPodcast($podcast),
    new OptimizePodcast($podcast),
    new ReleasePodcast($podcast),
])->dispatch();

Je kunt ook callbacks toevoegen die worden uitgevoerd wanneer de hele chain voltooid is of wanneer een job in de chain mislukt.

Bus::chain([
    new ProcessPodcast($podcast),
    new ReleasePodcast($podcast),
])->catch(function (Throwable $e) {
    // Afhandeling wanneer een job in de chain mislukt
})->dispatch();

Job batches

Met batches kun je meerdere jobs gebundeld dispatchen en de totale voortgang volgen. Maak eerst een migration voor de tabel job_batches.

php artisan make:batches-table
php artisan migrate

Gebruik de trait Batchable in je jobklasse.

<?php

namespace App\Jobs;

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

class ImportContacts implements ShouldQueue
{
    use Batchable, Queueable;

    public function handle(): void
    {
        if ($this->batch()->cancelled()) {
            return;
        }

        // Een chunk contacten importeren...
    }
}

Met Bus::batch() dispatch je een batch en kun je callbacks registreren voor voltooiing, mislukking en afronding.

use App\Jobs\ImportContacts;
use Illuminate\Bus\Batch;
use Illuminate\Support\Facades\Bus;
use Throwable;

$batch = Bus::batch([
    new ImportContacts($chunkA),
    new ImportContacts($chunkB),
    new ImportContacts($chunkC),
])->then(function (Batch $batch) {
    // Wanneer alle jobs succesvol zijn voltooid
})->catch(function (Batch $batch, Throwable $e) {
    // Wanneer een job mislukt
})->finally(function (Batch $batch) {
    // Wanneer de uitvoering van de batch klaar is
})->dispatch();

Met het batch-ID kun je de status van de batch opvragen.

$batch = Bus::findBatch($batchId);

$batch->totalJobs;      // Totaal aantal jobs
$batch->pendingJobs;    // Aantal wachtende jobs
$batch->failedJobs;     // Aantal mislukte jobs
$batch->progress();     // Voortgangspercentage (0–100)

Jobs verwerken

Het queue:work commando

Start een queue-worker om jobs te verwerken.

php artisan queue:work

Je kunt ook een specifieke driver of queue opgeven.

# Alleen de emails-queue van Redis verwerken
php artisan queue:work redis --queue=emails

# De databasedriver gebruiken
php artisan queue:work database

queue:work blijft na het starten draaien. Herstart de worker met queue:restart wanneer je de code hebt aangepast. In productie is het gebruikelijk om workers te beheren met een procesmanager zoals Supervisor.

Opties voor het beheren van queue-workers

Door veelgebruikte opties te combineren kun je de worker nauwkeurig aansturen.

php artisan queue:work --tries=3 --timeout=60 --sleep=3

Optie	Beschrijving
`--tries=N`	Maximaal aantal pogingen per job. Daarna wordt de job als mislukt geregistreerd
`--timeout=N`	Maximale uitvoeringstijd in seconden per job. Bij overschrijding wordt de worker geforceerd gestopt
`--sleep=N`	Aantal seconden wachten tot de volgende poll wanneer de queue leeg is (standaard: 3)
`--max-jobs=N`	Beëindig de worker na het verwerken van N jobs
`--max-time=N`	Beëindig de worker na N seconden
`--queue=A,B`	Verwerk queues met prioriteit (A heeft voorrang)

Retry-instellingen in de jobklasse zetten

Soms is het overzichtelijker om de instellingen in de jobklasse zelf te zetten in plaats van via commandolijnopties.

use Illuminate\Foundation\Queue\Queueable;
use Illuminate\Queue\Attributes\Tries;
use Illuminate\Queue\Attributes\Timeout;

#[Tries(3)]
#[Timeout(60)]
class SendWelcomeEmail implements ShouldQueue
{
    use Queueable;

    // ...
}

Jobs releasen (Release middleware)

Wil je een job onder bepaalde voorwaarden niet uitvoeren maar terugzetten op de queue, dan schrijf je dat beknopt met de Release-middleware.

use Illuminate\Queue\Middleware\Release;

/**
 * Geef de middleware terug waar de job doorheen gaat
 */
public function middleware(): array
{
    return [
        // Release na 60 seconden wanneer $condition true is
        Release::when($this->order->isPending(), releaseAfter: 60),
    ];
}

Release::unless() releaset wanneer de voorwaarde false is.

return [
    // Release na 60 seconden wanneer de bestelling nog niet betaald is
    Release::unless($this->order->isPaid(), releaseAfter: 60),
];

Met een closure kun je complexere voorwaarden beschrijven.

return [
    Release::when(function (): bool {
        return ! $this->order->isPaid();
    }, releaseAfter: 60),
];

Ook bij het releasen van een job wordt het aantal pogingen opgehoogd. Stel #[Tries] of de property $tries passend in.

Mislukte jobs afhandelen

De failed_jobs-tabel voorbereiden

Wanneer een job het maximale aantal pogingen overschrijdt, wordt hij vastgelegd in de tabel failed_jobs. Bestaat de tabel nog niet, maak hem dan aan met de volgende commando’s.

php artisan make:queue-failed-table
php artisan migrate

Opruimen bij mislukking

Definieer je een methode failed() op de job, dan kun je daar de afhandeling na een mislukking beschrijven.

use Throwable;

public function failed(?Throwable $exception): void
{
    // Bijvoorbeeld een Slack-notificatie naar de beheerder sturen
    // Notification::route('slack', config('app.slack_webhook'))
    //     ->notify(new JobFailedNotification($this, $exception));
}

Retries stoppen op basis van exceptions

Bij bepaalde soorten exceptions wil je de job niet opnieuw laten proberen maar direct laten mislukken. Geef binnen withExceptions() in bootstrap/app.php met dontRetry de betreffende exception classes op.

use App\Exceptions\InvalidPodcastSourceException;
use Illuminate\Foundation\Configuration\Exceptions;

->withExceptions(function (Exceptions $exceptions): void {
    $exceptions->dontRetry([
        InvalidPodcastSourceException::class,
    ]);
})

Heb je fijnmazigere controle nodig, geef dan een closure door aan dontRetryWhen. Wanneer de closure true teruggeeft, wordt de job direct als mislukt gemarkeerd en niet opnieuw geprobeerd.

use App\Exceptions\PodcastProcessingException;
use Illuminate\Foundation\Configuration\Exceptions;

->withExceptions(function (Exceptions $exceptions): void {
    $exceptions->dontRetryWhen(function (PodcastProcessingException $e) {
        return $e->reason() === 'Subscription expired';
    });
})

Bij exceptions waarvan het resultaat niet verandert hoe vaak je ook retryt — zoals validatiefouten of betalingsfouten (bijvoorbeeld een verlopen abonnement) — is het efficiënt om de job op deze manier direct te laten mislukken.

Overzicht van mislukte jobs bekijken

php artisan queue:failed

Mislukte jobs opnieuw proberen

# Een specifiek job-ID opnieuw proberen
php artisan queue:retry ce7bb17c-cdd8-41f0-a8ec-7b4fef4e5ece

# Alle mislukte jobs opnieuw proberen
php artisan queue:retry all

Mislukte jobs verwijderen

# Een specifieke job verwijderen
php artisan queue:forget ce7bb17c-cdd8-41f0-a8ec-7b4fef4e5ece

# Alle mislukte jobs verwijderen
php artisan queue:flush

Veelgebruikte queue-drivers

De database-driver

Een eenvoudige driver waarmee je zonder extra middleware aan de slag kunt. Jobs worden opgeslagen in de tabel jobs en workers pollen deze om ze te verwerken.

Voordelen: eenvoudige setup, je kunt je bestaande RDBMS direct gebruiken
Nadelen: hoge belasting op de database, dus minder geschikt voor grote aantallen jobs

QUEUE_CONNECTION=database

De redis-driver

De snelle driver die in productieomgevingen het meest wordt gebruikt. Omdat hij in-memory werkt is de doorvoer hoger dan bij een database en kun je grote aantallen jobs verwerken.

Voordelen: snel, schaalbaar
Nadelen: je hebt een Redis-server nodig

QUEUE_CONNECTION=redis
REDIS_HOST=127.0.0.1
REDIS_PORT=6379

Draai je Redis-queues in productie, overweeg dan Laravel Horizon te gebruiken. Met een fraai dashboard kun je de status van jobs in realtime monitoren.

Productiegebruik met Supervisor

In productie heb je een mechanisme nodig dat het queue:work-proces automatisch herstart wanneer het om welke reden dan ook stopt. Op Linux is het gebruikelijk om hiervoor Supervisor te gebruiken.

# /etc/supervisor/conf.d/laravel-worker.conf
[program:laravel-worker]
process_name=%(program_name)s_%(process_num)02d
command=php /var/www/your-app/artisan queue:work --sleep=3 --tries=3 --max-time=3600
autostart=true
autorestart=true
stopasgroup=true
killasgroup=true
user=www-data
numprocs=2
redirect_stderr=true
stdout_logfile=/var/www/your-app/storage/logs/worker.log
stopwaitsecs=3600

Met numprocs=2 start je twee workerprocessen parallel. Herlaad Supervisor na het instellen.

sudo supervisorctl reread
sudo supervisorctl update
sudo supervisorctl start laravel-worker:*

Praktijkvoorbeeld: e-mails versturen via de queue

Maak een jobklasse

php artisan make:job SendOrderConfirmation

Implementeer de verwerking van de job

<?php

namespace App\Jobs;

use App\Models\Order;
use App\Mail\OrderConfirmed;
use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Foundation\Queue\Queueable;
use Illuminate\Queue\Attributes\Tries;
use Illuminate\Queue\Attributes\Timeout;
use Illuminate\Support\Facades\Mail;

#[Tries(3)]
#[Timeout(30)]
class SendOrderConfirmation implements ShouldQueue
{
    use Queueable;

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

    public function handle(): void
    {
        Mail::to($this->order->user->email)
            ->send(new OrderConfirmed($this->order));
    }
}

Dispatch vanuit de controller

use App\Jobs\SendOrderConfirmation;

public function store(Request $request): RedirectResponse
{
    $order = Order::create($request->validated());

    SendOrderConfirmation::dispatch($order);

    return redirect()->route('orders.show', $order)
        ->with('success', 'Je bestelling is ontvangen.');
}

Start de worker

php artisan queue:work --tries=3 --timeout=30

Samenvatting

Wanneer je queues zou moeten gebruiken

E-mails en sms’jes versturen
Afbeeldingen en video’s verkleinen of converteren
Requests naar externe API’s
Rapporten genereren of CSV-exports maken
Webhooks versturen

Tips voor tijdens de ontwikkeling

Zet je in .env QUEUE_CONNECTION=sync, dan worden jobs direct uitgevoerd zonder de queue te gebruiken. Je kunt dan alles testen zonder een worker te starten, wat tijdens de ontwikkeling handig is.

QUEUE_CONNECTION=sync

Overzicht van veelgebruikte commando's

# Worker starten
php artisan queue:work

# Worker herstarten (na een deploy)
php artisan queue:restart

# Overzicht van mislukte jobs
php artisan queue:failed

# Alle mislukte jobs opnieuw proberen
php artisan queue:retry all

# Alle mislukte jobs verwijderen
php artisan queue:flush

​Wat is een queue?

​Queue-configuratie

​config/queue.php

​.env instellen

​De databasedriver voorbereiden

​De Redis-driver voorbereiden

​SQS Overflow Storage

​Een jobklasse maken

​Het make:job commando

​Structuur van een jobklasse

​Jobs dispatchen

​dispatch()

​Vertraagd dispatchen

​dispatchAfterResponse()

​Dispatchen naar een specifieke queue

​Queue Routing

​Queues doorsturen (Queue::forward())

​Synchroon uitvoeren (voor testen en ontwikkeling)

​Bulk dispatchen

​Job chains

​Job batches

​Jobs verwerken

​Het queue:work commando

​Opties voor het beheren van queue-workers

​Retry-instellingen in de jobklasse zetten

​Jobs releasen (Release middleware)

​Mislukte jobs afhandelen

​De failed_jobs-tabel voorbereiden

​Opruimen bij mislukking

​Retries stoppen op basis van exceptions

​Overzicht van mislukte jobs bekijken

​Mislukte jobs opnieuw proberen

​Mislukte jobs verwijderen

​Veelgebruikte queue-drivers

​De database-driver

​De redis-driver

​Productiegebruik met Supervisor

​Praktijkvoorbeeld: e-mails versturen via de queue

​Samenvatting

Wat is een queue?

Queue-configuratie

config/queue.php

.env instellen

De databasedriver voorbereiden

De Redis-driver voorbereiden

SQS Overflow Storage

Een jobklasse maken

Het make:job commando

Structuur van een jobklasse

Jobs dispatchen

dispatch()

Vertraagd dispatchen

dispatchAfterResponse()

Dispatchen naar een specifieke queue

Queue Routing

Queues doorsturen (`Queue::forward()`)

Synchroon uitvoeren (voor testen en ontwikkeling)

Bulk dispatchen

Job chains

Job batches

Jobs verwerken

Het queue:work commando

Opties voor het beheren van queue-workers

Retry-instellingen in de jobklasse zetten

Jobs releasen (Release middleware)

Mislukte jobs afhandelen

De failed_jobs-tabel voorbereiden

Opruimen bij mislukking

Retries stoppen op basis van exceptions

Overzicht van mislukte jobs bekijken

Mislukte jobs opnieuw proberen

Mislukte jobs verwijderen

Veelgebruikte queue-drivers

De database-driver

De redis-driver

Productiegebruik met Supervisor

Praktijkvoorbeeld: e-mails versturen via de queue

Samenvatting