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 => ['redis', 'podcasts'], // connection und queue
    ProcessVideo::class => 'videos',                // nur queue (Standardverbindung)
]);

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

Queues weiterleiten (`Queue::forward()`)

Mit Queue::forward() leiten Sie Jobs von einer Queue an eine andere Queue oder Verbindung weiter. Das ist praktisch, wenn Sie die Queue-Infrastruktur wechseln möchten, ohne einzelne Jobs oder den aufrufenden Code anzupassen.

use Illuminate\Support\Facades\Queue;

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

Um mehrere Queues auf einmal weiterzuleiten, übergeben Sie ein Array.

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

Gibt ein Job explizit eine Verbindung an, hat die Angabe des Jobs Vorrang vor der Weiterleitungskonfiguration.

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.

Job-Chains

Durch das Verketten von Jobs führen Sie mehrere Jobs nacheinander aus. Schlägt ein Job innerhalb der Kette fehl, werden die nachfolgenden Jobs nicht mehr ausgeführt.

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();

Sie können auch Callbacks registrieren, die ausgeführt werden, wenn die gesamte Kette abgeschlossen ist oder ein Job innerhalb der Kette fehlschlägt.

Bus::chain([
    new ProcessPodcast($podcast),
    new ReleasePodcast($podcast),
])->catch(function (Throwable $e) {
    // Verarbeitung, wenn ein Job in der Kette fehlgeschlagen ist
})->dispatch();

Job-Batches

Mit Batches dispatchen Sie mehrere Jobs gesammelt und verfolgen den Gesamtfortschritt. Erstellen Sie zunächst die Migration für die Tabelle job_batches.

php artisan make:batches-table
php artisan migrate

Verwenden Sie in der Job-Klasse das Trait Batchable.

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

        // Einen Chunk von Kontakten importieren ...
    }
}

Mit Bus::batch() dispatchen Sie den Batch und registrieren Callbacks für Abschluss, Fehler und das Ende der Verarbeitung.

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) {
    // Wenn alle Jobs erfolgreich abgeschlossen wurden
})->catch(function (Batch $batch, Throwable $e) {
    // Wenn ein Job fehlgeschlagen ist
})->finally(function (Batch $batch) {
    // Wenn die Ausführung des Batches beendet ist
})->dispatch();

Über die Batch-ID können Sie den Status des Batches abfragen.

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

$batch->totalJobs;      // Gesamtzahl der Jobs
$batch->pendingJobs;    // Anzahl wartender Jobs
$batch->failedJobs;     // Anzahl fehlgeschlagener Jobs
$batch->progress();     // Fortschritt (0–100)

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;

    // ...
}

Abstürze als Exceptions zählen

Standardmäßig werden Versuche, die enden, weil der Worker-Prozess abstürzt oder zwangsweise beendet wird (etwa wegen Speichermangels), nicht auf die maximale Anzahl an Exceptions des Jobs (MaxExceptions) angerechnet. Wenn auch diese Versuche als Exceptions gezählt werden sollen, fügen Sie der Job-Klasse das Attribut CountCrashesAsExceptions hinzu.

use Illuminate\Queue\Attributes\CountCrashesAsExceptions;
use Illuminate\Queue\Attributes\MaxExceptions;
use Illuminate\Queue\Attributes\Tries;

#[Tries(25)]
#[MaxExceptions(3)]
#[CountCrashesAsExceptions]
class ProcessPodcast implements ShouldQueue
{
    // ...
}

Mit diesem Attribut speichert der Worker während der Verarbeitung des Jobs eine Markierung im Cache der Anwendung. Ist diese Markierung beim nächsten Versuch des Jobs noch vorhanden, wird der vorherige Versuch als Exception gezählt.

Ausführungssteuerung mit Job-Middleware

Mit Job-Middleware können Sie übergreifende Logik wie Rate Limiting oder das Verhindern von Mehrfachausführungen aus der handle()-Methode auslagern und stattdessen deklarativ über die middleware()-Methode angeben. Da die Logik nicht im Job selbst steht, lässt sich dieselbe Steuerung leicht in mehreren Jobs wiederverwenden.

/**
 * Middleware zurückgeben, die der Job durchlaufen soll
 */
public function middleware(): array
{
    return [new RateLimited('backups')];
}

Eigene Job-Middleware können Sie mit dem Artisan-Befehl make:job-middleware generieren. Job-Middleware lässt sich außerdem für Queue-Event-Listener, Mailables und Notifications angeben.

Rate Limiting (RateLimited)

Definieren Sie das Rate Limit mit der for-Methode der RateLimiter-Facade und wenden Sie die Middleware Illuminate\Queue\Middleware\RateLimited auf den Job an.

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

// Definition in AppServiceProvider::boot()
RateLimiter::for('backups', function (object $job) {
    return $job->user->vipCustomer()
        ? Limit::none()
        : Limit::perHour(1)->by($job->user->id);
});

use Illuminate\Queue\Middleware\RateLimited;

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

Jobs, die das Limit überschreiten, werden abhängig von der verbleibenden Zeit des Rate Limits automatisch zurück in die Queue gelegt. Mit releaseAfter() legen Sie eine feste Wartezeit in Sekunden bis zum nächsten Versuch fest, mit dontRelease() beenden Sie den Job stattdessen sofort, ohne ihn erneut auszuführen.

public function middleware(): array
{
    return [(new RateLimited('backups'))->releaseAfter(60)];
    // Oder ohne erneuten Versuch:
    // return [(new RateLimited('backups'))->dontRelease()];
}

Auch freigegebene Jobs werden bei den Versuchen (attempts) mitgezählt. Konfigurieren Sie #[Tries] oder retryUntil() entsprechend.

Bei Verwendung von Redis steht die performantere Variante Illuminate\Queue\Middleware\RateLimitedWithRedis zur Verfügung.

use Illuminate\Queue\Middleware\RateLimitedWithRedis;

public function middleware(): array
{
    return [new RateLimitedWithRedis('backups')];
}

Mehrfachausführung verhindern (WithoutOverlapping)

Illuminate\Queue\Middleware\WithoutOverlapping verhindert anhand eines beliebigen Schlüssels, dass derselbe Job mehrfach parallel ausgeführt wird. Nützlich, wenn eine bestimmte Ressource jeweils nur von einem Job aktualisiert werden soll.

use Illuminate\Queue\Middleware\WithoutOverlapping;

public function middleware(): array
{
    // Verhindert, dass sich Jobs zur Kredit-Score-Aktualisierung derselben User-ID überschneiden
    return [new WithoutOverlapping($this->user->id)];
}

Überschneidende Jobs werden zurück in die Queue gelegt. Mit releaseAfter() steuern Sie den Wiederholungsabstand und mit dontRelease(), ob sie stattdessen sofort gelöscht werden. Da der Lock die Funktion Atomare Locks nutzt, empfiehlt es sich, mit expireAfter() eine Gültigkeitsdauer festzulegen, damit der Lock auch dann nicht dauerhaft bestehen bleibt, wenn der Job unerwartet fehlschlägt oder in ein Timeout läuft.

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

Standardmäßig werden Überschneidungen nur innerhalb derselben Job-Klasse verhindert. Sollen sich verschiedene Job-Klassen denselben Lock-Schlüssel teilen, verwenden Sie die Methode shared().

Aufeinanderfolgende Exceptions drosseln (ThrottlesExceptions)

Illuminate\Queue\Middleware\ThrottlesExceptions ist für Jobs gedacht, die mit instabilen Diensten wie externen APIs kommunizieren, und pausiert die weitere Ausführung, sobald in einer bestimmten Häufigkeit Exceptions auftreten. Üblicherweise wird die Middleware mit einer zeitbasierten Versuchsbegrenzung (retryUntil()) kombiniert.

use DateTime;
use Illuminate\Queue\Middleware\ThrottlesExceptions;

public function middleware(): array
{
    // Bei 10 aufeinanderfolgenden Exceptions die Job-Ausführung 5 Minuten pausieren
    return [new ThrottlesExceptions(10, 5 * 60)];
}

public function retryUntil(): DateTime
{
    return now()->addMinutes(30);
}

Mit when() können Sie das Throttling auf bestimmte Exceptions beschränken, mit deleteWhen() den Job bei einer bestimmten Exception vollständig löschen – so lassen sich auch feingranulare Steuerungen umsetzen.

use App\Exceptions\CustomerDeletedException;
use Illuminate\Http\Client\HttpClientException;
use Illuminate\Queue\Middleware\ThrottlesExceptions;

public function middleware(): array
{
    return [
        (new ThrottlesExceptions(10, 10 * 60))
            ->when(fn ($e) => $e instanceof HttpClientException)
            ->deleteWhen(CustomerDeletedException::class),
    ];
}

Bei Verwendung von Redis lässt sich mit Illuminate\Queue\Middleware\ThrottlesExceptionsWithRedis effizienter drosseln.

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

​Queues weiterleiten (Queue::forward())

​Synchrone Ausführung (Test/Entwicklung)

​Bulk-Dispatch

​Job-Chains

​Job-Batches

​Jobs verarbeiten

​queue:work

​Optionen zur Worker-Steuerung

​Retry-Einstellungen in der Job-Klasse

​Abstürze als Exceptions zählen

​Ausführungssteuerung mit Job-Middleware

​Rate Limiting (RateLimited)

​Mehrfachausführung verhindern (WithoutOverlapping)

​Aufeinanderfolgende Exceptions drosseln (ThrottlesExceptions)

​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

Queues weiterleiten (`Queue::forward()`)

Synchrone Ausführung (Test/Entwicklung)

Bulk-Dispatch

Job-Chains

Job-Batches

Jobs verarbeiten

`queue:work`

Optionen zur Worker-Steuerung

Retry-Einstellungen in der Job-Klasse

Abstürze als Exceptions zählen

Ausführungssteuerung mit Job-Middleware

Rate Limiting (RateLimited)

Mehrfachausführung verhindern (WithoutOverlapping)

Aufeinanderfolgende Exceptions drosseln (ThrottlesExceptions)

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