Files d'attente Laravel : Horizon, retries et jobs idempotents
12 Nov 2026 | Développement Web et Mobile
Les files d'attente (queues) sont l'un des outils les plus utiles de Laravel : envoi d'e-mails, génération de rapports, appels à des API externes, traitements lourds. Mais un système asynchrone introduit une réalité inconfortable : un job peut s'exécuter plus d'une fois, échouer à mi-parcours ou arriver dans le désordre. Voici comment bâtir des traitements fiables.
Rappel : choisir son driver
Pour un usage sérieux, évitez le driver sync (qui exécute tout immédiatement) et privilégiez database pour démarrer simplement, ou redis pour de meilleures performances. Laravel Horizon nécessite Redis et apporte un tableau de bord, la supervision des workers et des métriques.
Installer et configurer Horizon
composer require laravel/horizon
php artisan horizon:install
php artisan horizon
Dans config/horizon.php, vous définissez des superviseurs : quelles files ils traitent, combien de processus ils lancent et selon quelle stratégie. Séparez les files par priorité ou par nature (emails, reports, default) pour qu'un traitement lent ne bloque pas les messages urgents.
En production, lancez Horizon sous un superviseur de processus (Supervisor ou systemd) et exécutez php artisan horizon:terminate à chaque déploiement pour qu'il recharge le nouveau code : cette étape s'intègre dans un pipeline de déploiement avec GitHub Actions. Protégez l'accès au tableau de bord avec la porte d'autorisation prévue à cet effet.
Tentatives, backoff et délai d'expiration
Configurez explicitement le comportement de chaque job :
class SendInvoice implements ShouldQueue
{
use Queueable;
public int $tries = 5;
public int $timeout = 60;
public function backoff(): array
{
return [10, 60, 300]; // secondes avant chaque nouvelle tentative
}
}
Le backoff espace les tentatives pour laisser à un service externe le temps de se rétablir. Le timeout doit toujours rester inférieur au délai de réservation de la file (retry_after), sans quoi le même job peut être repris par un autre worker alors qu'il tourne encore.
Gérer les échecs
- Les jobs définitivement échoués sont stockés dans la table
failed_jobs(php artisan queue:failed-tablesi nécessaire). - Relancez-les avec
php artisan queue:retry allune fois la cause corrigée. - Implémentez la méthode
failed(Throwable $e)pour prévenir l'équipe ou annuler un état intermédiaire. - Utilisez les notifications d'échec de Horizon ou un outil de suivi d'erreurs.
Le cœur du sujet : l'idempotence
Un job est idempotent lorsque l'exécuter plusieurs fois produit le même résultat que l'exécuter une seule fois (nous détaillons la notion dans notre article sur les verbes HTTP). C'est indispensable, car une file garantit en général une livraison « au moins une fois » et non « exactement une fois ». Un worker qui plante après avoir envoyé un e-mail mais avant d'avoir marqué le job comme terminé enverra ce mail une seconde fois.
Technique 1 : tester l'état avant d'agir
public function handle(): void
{
if ($this->invoice->sent_at !== null) {
return; // déjà envoyé, on ne refait rien
}
Mail::to($this->invoice->customer)->send(new InvoiceMail($this->invoice));
$this->invoice->update(['sent_at' => now()]);
}
Technique 2 : une clé d'idempotence
Pour appeler une API de paiement ou créer une ressource externe, envoyez une clé unique et stable (par exemple dérivée de l'identifiant de la commande) afin que le service ignore les doublons. Beaucoup d'API de paiement proposent un en-tête dédié. Le même principe s'applique à l'envoi d'événements de conversion vers les plateformes publicitaires, comme dans notre audit du suivi des conversions.
Technique 3 : des opérations atomiques
Utilisez des transactions de base de données pour que l'état ne soit jamais à moitié mis à jour, et préférez des opérations comme updateOrCreate ou des contraintes d'unicité qui rendent l'opération naturellement répétable.
Éviter les doublons et les chevauchements
Laravel fournit des outils pour contrôler la concurrence :
ShouldBeUnique: empêche d'empiler plusieurs fois le même job tant qu'un exemplaire est en attente ou en cours.WithoutOverlapping(middleware de job) : empêche l'exécution simultanée de deux jobs portant sur la même clé.RateLimited: respecte la limite d'appels d'une API tierce.
public function middleware(): array
{
return [new WithoutOverlapping($this->invoice->id)];
}
Attention : ces mécanismes réduisent les doublons mais ne remplacent pas l'idempotence. Un verrou peut expirer, un worker peut mourir : la protection de fond reste dans le code du job.
Passer des identifiants, pas des objets lourds
Le trait SerializesModels sérialise un modèle sous forme d'identifiant puis le recharge au moment de l'exécution : le job travaille donc sur l'état courant de la base. C'est généralement souhaitable, mais pensez au cas où l'enregistrement a été supprimé entre-temps (deleteWhenMissingModels).
Chaînes et lots
Pour des traitements en plusieurs étapes, utilisez Bus::chain() (étapes séquentielles) ou Bus::batch() (jobs parallèles avec suivi global). Chaque étape doit rester idempotente, car c'est elle qui sera relancée en cas de reprise.
Surveiller et dimensionner
- Suivez le temps d'attente de chaque file : s'il augmente, ajoutez des workers.
- Évitez les jobs trop longs ; découpez-les en lots. C'est typiquement le cas des appels à un modèle d'IA, comme avec un LLM local via Ollama.
- Limitez la consommation mémoire des workers avec
--max-jobsou--memorypour qu'ils redémarrent proprement.
Conclusion
Horizon vous apporte la visibilité et le pilotage, mais la fiabilité d'un système de files repose sur l'écriture des jobs eux-mêmes. Partez du principe qu'un job sera rejoué, rendez-le idempotent, bornez ses tentatives et surveillez les échecs. Vous obtiendrez des traitements asynchrones sur lesquels vous pouvez compter.
Commentaires (0)
Aucun commentaire pour le moment.
Laissez un commentaire