Queues et jobs - Knowledge of Laravel

Qu’est-ce qu’une queue

Dans une application web, l’envoi de mails, le redimensionnement d’images ou les appels d’API externes peuvent prendre plusieurs secondes. Traiter cela de manière synchrone dans une requête HTTP fait attendre l’utilisateur inutilement. Les queues Laravel exécutent ces tâches en arrière-plan : la requête retourne immédiatement une réponse, et un worker traite le job à part.

Backends supportés : base de données, Redis, Amazon SQS… En dev, le driver sync exécute les jobs immédiatement, sans queue.

Configuration

`config/queue.php`

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

`.env`

# Sélection du driver
QUEUE_CONNECTION=database

# Redis
# QUEUE_CONNECTION=redis
# REDIS_HOST=127.0.0.1
# REDIS_PORT=6379

Préparer le driver database

database nécessite une table jobs. Sous Laravel 11+, la migration est incluse ; sinon :

php artisan make:queue-table
php artisan migrate

Préparer le driver Redis

Configurez la connexion Redis dans config/database.php puis installez :

composer require predis/predis

Overflow storage SQS

Amazon SQS limite la taille de payload. Pour de gros payloads, redirigez l’excédent vers un cache et n’envoyez qu’un pointeur.

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

enabled : payloads ≥ 1 Mo → cache.
always: true : toujours passer par le cache.
delete_after_processing : nettoie le cache après succès (true par défaut).
flush_on_clear: true : queue:clear purge le cache d’overflow. À combiner avec un store dédié pour ne pas vider le cache général.

Créer une classe de job

Commande `make:job`

php artisan make:job SendWelcomeEmail

Le fichier app/Jobs/SendWelcomeEmail.php est créé.

Structure

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

    /**
     * Instance du job.
     */
    public function __construct(
        public User $user,
    ) {}

    /**
     * Exécution du job.
     */
    public function handle(): void
    {
        Mail::to($this->user->email)->send(new WelcomeMail($this->user));
    }
}

ShouldQueue indique un traitement asynchrone. Le trait Queueable fournit les méthodes nécessaires.

Passer un modèle Eloquent au constructeur sérialise seulement son ID. Au moment de l’exécution, le modèle est récupéré à jour : payload allégé.

Dispatch

`dispatch()`

use App\Jobs\SendWelcomeEmail;

public function register(Request $request): RedirectResponse
{
    $user = User::create($request->validated());

    SendWelcomeEmail::dispatch($user);

    return redirect('/dashboard');
}

Dispatch différé

// 5 min plus tard
SendWelcomeEmail::dispatch($user)->delay(now()->addMinutes(5));

`dispatchAfterResponse()`

Exécute le job après l’envoi de la réponse HTTP. Fonctionne aussi en sync — idéal pour du léger sans worker.

SendWelcomeEmail::dispatchAfterResponse($user);

Vers une queue précise

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

Routing de queue

Pour rediriger par défaut certaines classes vers une connexion/queue précise, utilisez Queue::route() dans boot().

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

Ciblez interface, trait, classe parente… tout ce qui les implémente/étend est routé. Plusieurs routes en une :

Queue::route([
    ProcessPodcast::class => ['redis', 'podcasts'], // connexion et queue
    ProcessVideo::class => 'videos',                // queue seule (connexion par défaut)
]);

Un onQueue() / onConnection() explicite sur le job prime sur le routing.

Transfert de queues (`Queue::forward()`)

Queue::forward() transfère les jobs d’une queue vers une autre queue ou connexion. Pratique pour changer d’infrastructure de queues sans modifier chaque job ni le code appelant.

use Illuminate\Support\Facades\Queue;

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

Passez un tableau pour transférer plusieurs queues à la fois.

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

Si le job spécifie explicitement une connexion, ce réglage prime sur la configuration de transfert.

Sync (dev/tests)

dispatchSync() exécute immédiatement, sans queue.

SendWelcomeEmail::dispatchSync($user);

Bulk dispatch

Pour envoyer beaucoup de jobs indépendants d’un coup sans tracking : Bus::bulk().

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

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

Bus::bulk() groupe les jobs par connexion/queue et les envoie par lot. Contrairement à Bus::batch(), pas de suivi ni de callback.

Chaînes de jobs

Le chaînage permet d’exécuter plusieurs jobs dans l’ordre. Si un job de la chaîne échoue, les jobs suivants ne sont pas exécutés.

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

Vous pouvez aussi ajouter un callback exécuté lorsque la chaîne entière est terminée, ou lorsqu’un job de la chaîne échoue.

Bus::chain([
    new ProcessPodcast($podcast),
    new ReleasePodcast($podcast),
])->catch(function (Throwable $e) {
    // Traitement en cas d'échec d'un job de la chaîne
})->dispatch();

Batches de jobs

Les batches permettent de dispatcher plusieurs jobs d’un coup tout en suivant la progression globale. Commencez par créer la migration pour la table job_batches.

php artisan make:batches-table
php artisan migrate

Utilisez le trait Batchable dans la classe de job.

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

        // Importer un chunk de contacts...
    }
}

Dispatchez le batch avec Bus::batch() et enregistrez des callbacks de succès, d’échec et de fin.

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) {
    // Tous les jobs se sont terminés avec succès
})->catch(function (Batch $batch, Throwable $e) {
    // Un job a échoué
})->finally(function (Batch $batch) {
    // L'exécution du batch est terminée
})->dispatch();

L’ID du batch permet d’en consulter l’état.

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

$batch->totalJobs;      // Nombre total de jobs
$batch->pendingJobs;    // Nombre de jobs en attente
$batch->failedJobs;     // Nombre de jobs échoués
$batch->progress();     // Progression (0 à 100)

Traiter les jobs

`queue:work`

php artisan queue:work

Ciblez driver et file :

# File emails sur Redis
php artisan queue:work redis --queue=emails

# Driver database
php artisan queue:work database

queue:work reste actif. Après un changement de code, queue:restart recharge les workers. En production, un superviseur (Supervisor…) est recommandé.

Options de supervision

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

Option	Description
`--tries=N`	Tentatives max ; au-delà, échec
`--timeout=N`	Durée max d’un job (secondes)
`--sleep=N`	Attente entre polls quand la file est vide (3 s)
`--max-jobs=N`	Termine après N jobs
`--max-time=N`	Termine après N secondes
`--queue=A,B`	Priorise A avant B

Retry paramétré côté job

Souvent plus lisible que la CLI.

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;

    // ...
}

Compter les crashs comme des exceptions

Par défaut, les tentatives qui se terminent par un crash ou un arrêt forcé du processus worker, par exemple à cause d’un manque de mémoire, ne sont pas comptées dans le nombre maximal d’exceptions du job (MaxExceptions). Si vous voulez que ces tentatives soient aussi comptées comme des exceptions, ajoutez l’attribut CountCrashesAsExceptions à la classe du job.

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

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

Avec cet attribut, le worker enregistre un marqueur dans le cache de l’application pendant le traitement du job. Si le marqueur est toujours présent lors de la tentative suivante, la tentative précédente est comptée comme une exception.

Contrôler l’exécution avec des middlewares de job

Les middlewares de job permettent d’extraire une logique transverse (limitation de débit, prévention des exécutions concurrentes…) hors de la méthode handle() et de la déclarer de façon déclarative via la méthode middleware(). Comme la logique ne vit plus dans le corps du job, il devient facile de réutiliser les mêmes contrôles sur plusieurs jobs.

/**
 * Retourne les middlewares que le job doit traverser.
 */
public function middleware(): array
{
    return [new RateLimited('backups')];
}

Générez vos propres middlewares de job avec la commande Artisan make:job-middleware. Les middlewares de job s’utilisent aussi sur les écouteurs d’événements en queue, les mailables et les notifications.

Limitation de débit (RateLimited)

Définissez la limite avec la méthode for de la façade RateLimiter, puis appliquez le middleware Illuminate\Queue\Middleware\RateLimited au job.

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

// À définir dans 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')];
}

Les jobs qui dépassent la limite sont automatiquement remis dans la queue en fonction du temps restant avant réinitialisation. Vous pouvez fixer un délai avec releaseAfter(), ou empêcher toute nouvelle tentative avec dontRelease().

public function middleware(): array
{
    return [(new RateLimited('backups'))->releaseAfter(60)];
    // ou, sans relance
    // return [(new RateLimited('backups'))->dontRelease()];
}

Un job libéré compte toujours dans le nombre de tentatives (attempts). Réglez #[Tries] ou retryUntil() en conséquence.

Si vous utilisez Redis, Illuminate\Queue\Middleware\RateLimitedWithRedis offre une variante plus performante.

use Illuminate\Queue\Middleware\RateLimitedWithRedis;

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

Prévention des exécutions concurrentes (WithoutOverlapping)

Illuminate\Queue\Middleware\WithoutOverlapping empêche plusieurs instances du même job de s’exécuter simultanément sur une clé donnée. Utile lorsqu’une ressource ne doit être mise à jour qu’une seule à la fois.

use Illuminate\Queue\Middleware\WithoutOverlapping;

public function middleware(): array
{
    // Empêche deux jobs de mise à jour du score d'un même utilisateur de se chevaucher
    return [new WithoutOverlapping($this->user->id)];
}

Les jobs en doublon sont remis dans la queue ; releaseAfter() définit l’intervalle avant réessai, et dontRelease() les supprime immédiatement. Comme les verrous s’appuient sur les verrous atomiques, pensez à préciser une expiration avec expireAfter() afin qu’un job qui échoue ou dépasse son délai ne laisse pas un verrou coincé.

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

Par défaut, le verrouillage n’agit qu’à l’intérieur d’une même classe de job. Pour partager la clé de verrou entre plusieurs classes de jobs, utilisez la méthode shared().

Étouffer les exceptions en rafale (ThrottlesExceptions)

Illuminate\Queue\Middleware\ThrottlesExceptions sert aux jobs qui interagissent avec des services instables (API externes…) : dès qu’un certain nombre d’exceptions se produisent, l’exécution est mise en pause pendant un temps donné. On l’associe généralement à une limite d’essais dans le temps via retryUntil().

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

public function middleware(): array
{
    // Après 10 exceptions consécutives, met le job en pause 5 minutes
    return [new ThrottlesExceptions(10, 5 * 60)];
}

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

when() permet de cibler certaines exceptions seulement, et deleteWhen() supprime le job lorsqu’une exception précise est levée.

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),
    ];
}

Avec Redis, Illuminate\Queue\Middleware\ThrottlesExceptionsWithRedis propose une implémentation plus efficace.

Libération de job (middleware Release)

Pour renvoyer le job dans la queue sans l’exécuter, sous condition, utilisez le middleware Release.

use Illuminate\Queue\Middleware\Release;

/**
 * Middlewares que le job traverse.
 */
public function middleware(): array
{
    return [
        // Si $condition == true, libère après 60 s
        Release::when($this->order->isPending(), releaseAfter: 60),
    ];
}

Release::unless() libère si la condition est false.

return [
    Release::unless($this->order->isPaid(), releaseAfter: 60),
];

Une closure pour des cas plus complexes :

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

Chaque libération incrémente le compteur d’essais. Réglez #[Tries] ou $tries en conséquence.

Jobs échoués

Table `failed_jobs`

Après épuisement des tentatives, le job est stocké dans failed_jobs.

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

Cleanup à l’échec

Définissez failed() sur le job.

use Throwable;

public function failed(?Throwable $exception): void
{
    // Notifier un admin Slack, etc.
    // Notification::route('slack', config('app.slack_webhook'))
    //     ->notify(new JobFailedNotification($this, $exception));
}

Arrêter les retries par type d’exception

Utilisez dontRetry dans withExceptions() (fichier bootstrap/app.php).

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

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

Avec une closure pour un contrôle fin :

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

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

Idéal pour des cas où retenter ne changera rien (validation, échec de paiement, abonnement expiré…).

Lister les échecs

php artisan queue:failed

Retry

# Un job précis
php artisan queue:retry ce7bb17c-cdd8-41f0-a8ec-7b4fef4e5ece

# Tous
php artisan queue:retry all

Suppression

# Un job
php artisan queue:forget ce7bb17c-cdd8-41f0-a8ec-7b4fef4e5ece

# Tous
php artisan queue:flush

Drivers courants

`database`

Simple à mettre en place, utilise la RDBMS existante.

Avantages : setup rapide, sans dépendance
Inconvénients : lourd pour de gros volumes

QUEUE_CONNECTION=database

`redis`

Driver rapide, très utilisé en production. Débit supérieur.

Avantages : rapide, scalable
Inconvénients : nécessite Redis

QUEUE_CONNECTION=redis
REDIS_HOST=127.0.0.1
REDIS_PORT=6379

En production, Laravel Horizon offre un beau dashboard pour surveiller les jobs Redis en temps réel.

Supervisor en production

Sous Linux, faites tourner queue:work en continu avec Supervisor.

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

numprocs=2 démarre 2 workers en parallèle. Rechargez Supervisor :

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

Exemple : envoi d’e-mail en queue

Créer le job

php artisan make:job SendOrderConfirmation

Implémenter

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

Dispatcher depuis un contrôleur

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', 'Commande enregistrée.');
}

Démarrer un worker

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

Récapitulatif

Quand utiliser une queue

Envoi de mails / SMS
Redimensionnement d’images / vidéos
Appels d’API externes
Génération de rapports / exports CSV
Envoi de webhooks

Astuce en dev

QUEUE_CONNECTION=sync dans .env exécute immédiatement — pas besoin de worker pour tester.

QUEUE_CONNECTION=sync

Commandes fréquentes

php artisan queue:work

php artisan queue:restart

php artisan queue:failed

php artisan queue:retry all

php artisan queue:flush

​Qu’est-ce qu’une queue

​Configuration

​config/queue.php

​.env

​Préparer le driver database

​Préparer le driver Redis

​Overflow storage SQS

​Créer une classe de job

​Commande make:job

​Structure

​Dispatch

​dispatch()

​Dispatch différé

​dispatchAfterResponse()

​Vers une queue précise

​Routing de queue

​Transfert de queues (Queue::forward())

​Sync (dev/tests)

​Bulk dispatch

​Chaînes de jobs

​Batches de jobs

​Traiter les jobs

​queue:work

​Options de supervision

​Retry paramétré côté job

​Compter les crashs comme des exceptions

​Contrôler l’exécution avec des middlewares de job

​Limitation de débit (RateLimited)

​Prévention des exécutions concurrentes (WithoutOverlapping)

​Étouffer les exceptions en rafale (ThrottlesExceptions)

​Libération de job (middleware Release)

​Jobs échoués

​Table failed_jobs

​Cleanup à l’échec

​Arrêter les retries par type d’exception

​Lister les échecs

​Retry

​Suppression

​Drivers courants

​database

​redis

​Supervisor en production

​Exemple : envoi d’e-mail en queue

​Récapitulatif

Qu’est-ce qu’une queue

Configuration

`config/queue.php`

`.env`

Préparer le driver database

Préparer le driver Redis

Overflow storage SQS

Créer une classe de job

Commande `make:job`

Structure

Dispatch

`dispatch()`

Dispatch différé

`dispatchAfterResponse()`

Vers une queue précise

Routing de queue

Transfert de queues (`Queue::forward()`)

Sync (dev/tests)

Bulk dispatch

Chaînes de jobs

Batches de jobs

Traiter les jobs

`queue:work`

Options de supervision

Retry paramétré côté job

Compter les crashs comme des exceptions

Contrôler l’exécution avec des middlewares de job

Limitation de débit (RateLimited)

Prévention des exécutions concurrentes (WithoutOverlapping)

Étouffer les exceptions en rafale (ThrottlesExceptions)

Libération de job (middleware Release)

Jobs échoués

Table `failed_jobs`

Cleanup à l’échec

Arrêter les retries par type d’exception

Lister les échecs

Retry

Suppression

Drivers courants

`database`

`redis`

Supervisor en production

Exemple : envoi d’e-mail en queue

Récapitulatif