Queues und Jobs - Knowledge of Laravel

Was sind Queues

In Web-Anwendungen gibt es Vorgänge – z. B. E-Mail-Versand, Bildskalierung oder Aufrufe externer APIs – die mehrere Sekunden dauern können. Erledigen Sie diese synchron innerhalb eines HTTP-Requests, muss der Nutzer bis zur Antwort warten. Mit Laravels Queues erledigen Sie solche schweren Aufgaben asynchron im Hintergrund. Der Request liefert sofort die Antwort, die eigentliche Arbeit übernimmt ein Worker-Prozess.

Queues unterstützen mehrere Backends wie Datenbank, Redis oder Amazon SQS. In der Entwicklung führt der Treiber sync Jobs direkt aus, ohne eine echte Queue zu nutzen.

Queue-Konfiguration

config/queue.php

Die Queue-Konfiguration liegt in config/queue.php. Über die Umgebungsvariable QUEUE_CONNECTION wählen Sie den Treiber.

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

`.env`-Konfiguration

# Treiber wählen
QUEUE_CONNECTION=database

# Für Redis
# QUEUE_CONNECTION=redis
# REDIS_HOST=127.0.0.1
# REDIS_PORT=6379

Vorbereitung des Datenbank-Treibers

Für den database-Treiber braucht es eine Tabelle. In neuen Laravel-11-Projekten ist die Migration bereits enthalten – andernfalls erzeugen Sie sie so:

php artisan make:queue-table
php artisan migrate

Vorbereitung des Redis-Treibers

Für den redis-Treiber ergänzen Sie in config/database.php die Redis-Verbindung und installieren den Client.

composer require predis/predis

SQS Overflow Storage

Amazon SQS begrenzt die Größe der Nachrichten-Payload. Für Jobs mit großen Payloads speichern Sie den Überschuss in einem Cache-Store und schicken an SQS nur einen Pointer.

'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),
    ],
],

Mit enabled werden Payloads ab 1 MB in den angegebenen Cache-Store ausgelagert.
Mit always: true werden alle SQS-Payloads unabhängig von der Größe im Cache-Store abgelegt.
delete_after_processing entfernt gespeicherte Payloads nach erfolgreicher Verarbeitung (Standard: true).
flush_on_clear löscht bei queue:clear den Overflow-Store. Nutzen Sie hier einen dedizierten Store, damit nicht der normale Cache mitgeleert wird.

Job-Klassen erstellen

`make:job`

Erzeugen Sie ein Grundgerüst mit dem Artisan-Befehl make:job.

php artisan make:job SendWelcomeEmail

Dies erzeugt app/Jobs/SendWelcomeEmail.php.

Aufbau einer Job-Klasse

<?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;

    /**
     * Erzeugt eine neue Job-Instanz.
     */
    public function __construct(
        public User $user,
    ) {}

    /**
     * Führt den Job aus.
     */
    public function handle(): void
    {
        Mail::to($this->user->email)->send(new WelcomeMail($this->user));
    }
}

Das Interface ShouldQueue signalisiert Laravel, dass der Job in einer Queue asynchron verarbeitet werden soll. Das Trait Queueable liefert die für Queue-Operationen benötigten Methoden.

Übergeben Sie dem Konstruktor ein Eloquent-Modell, serialisiert Laravel automatisch nur die ID. Bei der Ausführung werden die Daten frisch aus der Datenbank geladen – die Payload bleibt schlank.

Jobs dispatchen

`dispatch()`

Aus Controllern oder Services stellen Sie einen Job mit dispatch() in die Queue.

use App\Jobs\SendWelcomeEmail;

// In einer Route oder einem Controller
public function register(Request $request): RedirectResponse
{
    $user = User::create($request->validated());

    // Job in die Queue stellen
    SendWelcomeEmail::dispatch($user);

    return redirect('/dashboard');
}

Verzögerter Dispatch

Mit delay() verschieben Sie die Ausführung.

// In 5 Minuten ausführen
SendWelcomeEmail::dispatch($user)->delay(now()->addMinutes(5));

`dispatchAfterResponse()`

Mit dispatchAfterResponse() läuft der Job unmittelbar nach dem Ausliefern der HTTP-Antwort. Es funktioniert auch mit dem sync-Treiber und eignet sich daher für kleine Aufgaben, die keinen eigenen Worker brauchen.

SendWelcomeEmail::dispatchAfterResponse($user);

Dispatch in eine bestimmte Queue

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

Queue Routing

Um bestimmte Job-Klassen standardmäßig einer bestimmten Verbindung oder Queue zuzuordnen, verwenden Sie in der boot()-Methode eines Service-Providers Queue::route(). So verwalten Sie Zuordnungen zentral, ohne in jeder Job-Klasse onQueue() / onConnection() zu schreiben.

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');
}

Sie können auch Interfaces, Traits oder Elternklassen angeben – die Regel gilt dann für alle Jobs, die diese implementieren, verwenden oder erweitern. Mehrere Jobs auf einmal:

Queue::route([
    ProcessPodcast::class => ['podcasts', 'redis'], // queue und connection
    ProcessVideo::class => 'videos',                // nur queue (Standardverbindung)
]);

Queue Routing lässt sich vom Job aus über onQueue() / onConnection() überschreiben.

Synchrone Ausführung (Test/Entwicklung)

dispatchSync() führt den Job unmittelbar aus, ohne die Queue zu benutzen.

SendWelcomeEmail::dispatchSync($user);

Bulk-Dispatch

Wenn Sie viele unabhängige Jobs auf einmal dispatchen möchten, verwenden Sie die Methode bulk() der Fassade Bus. Ideal, wenn Sie keine Batch-Nachverfolgung oder Callbacks benötigen. Bus::bulk() gruppiert die Jobs nach Verbindung und Queue-Name und pusht jede Gruppe gesammelt – das ist effizient.

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

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

Bus::bulk() schickt Jobs gesammelt als Batch in die Queue. Anders als bei Batch-Verarbeitung (Bus::batch()) gibt es kein Fortschritts-Tracking und keine Completion-Callbacks. Ideal, um viele unabhängige Jobs einfach in großem Volumen zu senden.

Jobs verarbeiten

`queue:work`

Starten Sie einen Queue-Worker, um Jobs abzuarbeiten.

php artisan queue:work

Sie können Treiber oder Queue gezielt angeben.

# Nur die Queue "emails" auf Redis
php artisan queue:work redis --queue=emails

# database-Treiber
php artisan queue:work database

queue:work läuft dauerhaft. Nach Codeänderungen starten Sie die Worker mit queue:restart neu. In Produktion managen Sie sie typischerweise mit einem Prozessmanager wie Supervisor.

Optionen zur Worker-Steuerung

Häufig genutzte Optionen können Sie kombinieren.

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

Option	Beschreibung
`--tries=N`	Maximale Versuche eines Jobs. Danach gilt der Job als fehlgeschlagen
`--timeout=N`	Maximaldauer eines Jobs in Sekunden. Bei Überschreitung wird der Worker abgebrochen
`--sleep=N`	Wartezeit in Sekunden bis zur nächsten Poll-Anfrage, wenn die Queue leer ist (Standard: 3)
`--max-jobs=N`	Beendet den Worker nach N verarbeiteten Jobs
`--max-time=N`	Beendet den Worker nach N Sekunden
`--queue=A,B`	Bearbeitet die Queues mit Priorisierung (A zuerst)

Retry-Einstellungen in der Job-Klasse

Statt Kommandozeilenoptionen kann es übersichtlicher sein, die Einstellungen direkt in der Job-Klasse zu definieren.

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;

    // ...
}

Job wieder freigeben (Release-Middleware)

Wenn ein Job unter bestimmten Bedingungen nicht ausgeführt, sondern zurück in die Queue gelegt werden soll, verwenden Sie die Release-Middleware.

use Illuminate\Queue\Middleware\Release;

/**
 * Middleware zurückgeben, die der Job durchläuft.
 */
public function middleware(): array
{
    return [
        // Wenn $condition true ist, in 60 Sekunden erneut freigeben
        Release::when($this->order->isPending(), releaseAfter: 60),
    ];
}

Release::unless() gibt frei, wenn die Bedingung false ist.

return [
    // Solange die Bestellung nicht bezahlt ist, in 60 Sekunden erneut freigeben
    Release::unless($this->order->isPaid(), releaseAfter: 60),
];

Für komplexere Bedingungen übergeben Sie eine Closure.

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

Ein Release erhöht den Versuchszähler des Jobs. Setzen Sie #[Tries] bzw. $tries passend.

Fehlgeschlagene Jobs

Tabelle `failed_jobs` einrichten

Überschreitet ein Job die maximale Anzahl an Versuchen, landet er in der Tabelle failed_jobs. Falls die Tabelle fehlt:

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

Aufräumen im Fehlerfall

Definieren Sie in der Job-Klasse die Methode failed(), um im Fehlerfall aufzuräumen.

use Throwable;

public function failed(?Throwable $exception): void
{
    // z. B. eine Slack-Benachrichtigung an Admins senden
    // Notification::route('slack', config('app.slack_webhook'))
    //     ->notify(new JobFailedNotification($this, $exception));
}

Retries für bestimmte Exceptions unterbinden

Manchmal möchte man bei bestimmten Exceptions gar nicht erst retryen. In bootstrap/app.php innerhalb von withExceptions() verwenden Sie dontRetry.

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

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

Für feinere Kontrolle nutzen Sie dontRetryWhen mit einer Closure. Gibt sie true zurück, wird der Job sofort als fehlgeschlagen markiert und nicht mehr retryet.

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

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

Bei Fehlern, deren Ergebnis sich durch Retries nicht ändert – etwa Validierungsfehler oder eine abgelaufene Zahlungs-Subscription – ist ein sofortiges Fehlschlagen effizienter.

Liste fehlgeschlagener Jobs

php artisan queue:failed

Fehlgeschlagene Jobs erneut ausführen

# Bestimmte Job-ID retryen
php artisan queue:retry ce7bb17c-cdd8-41f0-a8ec-7b4fef4e5ece

# Alle retryen
php artisan queue:retry all

Fehlgeschlagene Jobs löschen

# Einzelnen Job löschen
php artisan queue:forget ce7bb17c-cdd8-41f0-a8ec-7b4fef4e5ece

# Alle löschen
php artisan queue:flush

Häufig verwendete Queue-Treiber

`database`-Treiber

Ein einfacher Treiber, ohne zusätzliche Infrastruktur direkt einsetzbar. Jobs landen in der Tabelle jobs, Worker pollen diese und verarbeiten sie.

Vorteile: einfache Einrichtung, nutzt Ihre vorhandene RDBMS
Nachteile: erhöht die DB-Last – für sehr viele Jobs weniger geeignet

QUEUE_CONNECTION=database

`redis`-Treiber

Der in Produktion am häufigsten verwendete, schnelle Treiber. Da Redis im Speicher arbeitet, sind Durchsatz und Skalierung deutlich besser.

Vorteile: schnell, skalierbar
Nachteile: Redis-Server erforderlich

QUEUE_CONNECTION=redis
REDIS_HOST=127.0.0.1
REDIS_PORT=6379

Für Redis-Queues in Produktion sollten Sie Laravel Horizon in Betracht ziehen. Es bietet ein schönes Dashboard mit Echtzeit-Überblick über die Jobs.

Produktivbetrieb mit Supervisor

In Produktion sollten queue:work-Prozesse bei einem Ausfall automatisch neu starten. Unter Linux ist Supervisor der Klassiker.

# /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

Mit numprocs=2 starten Sie zwei Worker parallel. Danach Supervisor neu einlesen:

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

Beispiel: E-Mail-Versand via Queue

Job-Klasse erstellen

php artisan make:job SendOrderConfirmation

Job-Logik implementieren

<?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));
    }
}

Aus dem Controller dispatchen

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', 'Bestellung angenommen.');
}

Worker starten

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

Zusammenfassung

Wann Queues nutzen?

E-Mail-/SMS-Versand
Bilder-/Videokonvertierung
Aufrufe externer APIs
Report- oder CSV-Erstellung
Webhook-Versand

Tipp für die Entwicklung

Setzen Sie in der .env QUEUE_CONNECTION=sync, werden Jobs direkt ausgeführt. So funktioniert alles auch ohne Worker – ideal beim Entwickeln.

QUEUE_CONNECTION=sync

Wichtige Befehle

# Worker starten
php artisan queue:work

# Worker neu starten (nach Deployment)
php artisan queue:restart

# Liste fehlgeschlagener Jobs
php artisan queue:failed

# Alle fehlgeschlagenen Jobs erneut ausführen
php artisan queue:retry all

# Alle fehlgeschlagenen Jobs löschen
php artisan queue:flush

​Was sind Queues

​Queue-Konfiguration

​config/queue.php

​.env-Konfiguration

​Vorbereitung des Datenbank-Treibers

​Vorbereitung des Redis-Treibers

​SQS Overflow Storage

​Job-Klassen erstellen

​make:job

​Aufbau einer Job-Klasse

​Jobs dispatchen

​dispatch()

​Verzögerter Dispatch

​dispatchAfterResponse()

​Dispatch in eine bestimmte Queue

​Queue Routing

​Synchrone Ausführung (Test/Entwicklung)

​Bulk-Dispatch

​Jobs verarbeiten

​queue:work

​Optionen zur Worker-Steuerung

​Retry-Einstellungen in der Job-Klasse

​Job wieder freigeben (Release-Middleware)

​Fehlgeschlagene Jobs

​Tabelle failed_jobs einrichten

​Aufräumen im Fehlerfall

​Retries für bestimmte Exceptions unterbinden

​Liste fehlgeschlagener Jobs

​Fehlgeschlagene Jobs erneut ausführen

​Fehlgeschlagene Jobs löschen

​Häufig verwendete Queue-Treiber

​database-Treiber

​redis-Treiber

​Produktivbetrieb mit Supervisor

​Beispiel: E-Mail-Versand via Queue

​Zusammenfassung

Was sind Queues

Queue-Konfiguration

config/queue.php

`.env`-Konfiguration

Vorbereitung des Datenbank-Treibers

Vorbereitung des Redis-Treibers

SQS Overflow Storage

Job-Klassen erstellen

`make:job`

Aufbau einer Job-Klasse

Jobs dispatchen

`dispatch()`

Verzögerter Dispatch

`dispatchAfterResponse()`

Dispatch in eine bestimmte Queue

Queue Routing

Synchrone Ausführung (Test/Entwicklung)

Bulk-Dispatch

Jobs verarbeiten

`queue:work`

Optionen zur Worker-Steuerung

Retry-Einstellungen in der Job-Klasse

Job wieder freigeben (Release-Middleware)

Fehlgeschlagene Jobs

Tabelle `failed_jobs` einrichten

Aufräumen im Fehlerfall

Retries für bestimmte Exceptions unterbinden

Liste fehlgeschlagener Jobs

Fehlgeschlagene Jobs erneut ausführen

Fehlgeschlagene Jobs löschen

Häufig verwendete Queue-Treiber

`database`-Treiber

`redis`-Treiber

Produktivbetrieb mit Supervisor

Beispiel: E-Mail-Versand via Queue

Zusammenfassung