Passer au contenu principal
Lorsque vous concevez les nouvelles tentatives d’un job en file, traitez séparément quatre questions : combien de fois essayer, jusqu’à quand essayer, combien d’exceptions tolérer et combien de secondes attendre avant la tentative suivante. Dans Laravel 13, vous pouvez déclarer chacune d’elles avec des attributs et des méthodes du job.
Cette page porte sur Laravel 13 et Framework v13.42.0. Elle ne traite pas de l’utilisation de base des files, mais de la combinaison des paramètres de nouvelle tentative et de leur ordre de priorité.

Séparer le nombre de tentatives de l’échéance

Dans Laravel, une « tentative » n’est pas seulement un appel réussi à handle(). Les exceptions non gérées, release(), les libérations par un middleware comme WithoutOverlapping ou RateLimited et les timeouts consomment aussi des tentatives. Si vous ne précisez rien, le worker n’essaie le job qu’une seule fois.

Tries : plafonner le nombre de tentatives

Vous pouvez déclarer une limite par job avec l’attribut Tries. Le paramètre du job prime sur l’option --tries du worker.
Pour déterminer la limite à partir de conditions à l’exécution, utilisez la méthode tries(). Cette méthode prime sur l’attribut Tries.

RetryFor : définir une fenêtre de temps

Pour limiter les nouvelles tentatives par le temps écoulé depuis la mise en file plutôt que par leur nombre, utilisez RetryFor. Un argument positionnel simple est un nombre de secondes, et vous pouvez aussi passer minutes et hours en arguments nommés.
Les déclarations suivantes expriment respectivement des secondes, des minutes et des heures.
RetryFor enregistre l’échéance dans le payload du job. Le worker ne lance pas de nouvelle tentative d’un job dont l’échéance est dépassée. Si le job possède une méthode retryUntil() ou une propriété retryUntil, celle-ci prime sur RetryFor. De plus, pour un job où retryUntil est actif, l’échéance temporelle prime sur Tries.
retryUntil() convient lorsque l’échéance dépend du contenu du job, comme l’heure de rétablissement prévue d’un service externe ou une date butoir métier.

Limiter les exceptions non gérées

Vous pouvez vouloir continuer à autoriser les appels manuels à release() et les libérations pendant l’attente d’un verrou, tout en échouant rapidement quand les exceptions non gérées se répètent. Dans ce cas, précisez Tries et MaxExceptions séparément.
Dans cet exemple, le job peut être tenté jusqu’à 25 fois. Cependant, après 3 exceptions non gérées, il échoue même si la limite de tentatives n’est pas atteinte. MaxExceptions ne compte pas les nouvelles tentatives dues à release(). Par défaut, les tentatives où le processus a planté (par exemple faute de mémoire) ne comptent pas comme exceptions pour MaxExceptions. Si les plantages doivent aussi compter comme exceptions, ajoutez CountCrashesAsExceptions.

Définir l’intervalle entre tentatives

Un job qui lève une exception est normalement libéré à nouveau dans la file. Vous pouvez définir l’attente avant la tentative suivante avec l’attribut Backoff ou la méthode backoff().

Intervalle fixe

Avec un tableau, vous pouvez utiliser un intervalle différent à chaque tentative. Une fois les éléments épuisés, la dernière valeur est utilisée.
Pour faire varier l’intervalle selon les conditions, utilisez backoff(). backoff() prime sur l’attribut Backoff.
Si le job ne précise rien, l’option --backoff du worker est utilisée.

Libérer les jobs en attente avec le même backoff

Pour relancer un job plus tard sans lever d’exception, par exemple lorsqu’une API externe répond « en cours de traitement », utilisez releaseUsingBackoff(). Le job est libéré avec la valeur du tableau de backoff du job qui correspond à la tentative en cours. Une fois les valeurs épuisées, la dernière est utilisée, et sans backoff le job est libéré immédiatement.
La libération automatique sur exception et la libération manuelle avec releaseUsingBackoff() ont des objectifs différents.
  • Sur exception : le job n’a pas pu être traité, Laravel le libère donc en utilisant le backoff.
  • Libération manuelle : le traitement lui-même est correct, mais le job est relancé plus tard, une fois l’état externe modifié.
L’attente de releaseUsingBackoff() provient du Backoff ou du backoff() du job. Pour indiquer explicitement une autre attente lors d’une libération manuelle, utilisez release(secondes).

Exemple combiné

Le job suivant est relancé pendant une heure au maximum et tolère jusqu’à 3 exceptions non gérées. En cas d’exception et lors des libérations manuelles en attente du paiement, il utilise des intervalles de 10, 30 et 60 secondes.
Lorsque RetryFor est présent, le worker utilise l’échéance plutôt que Tries(25) comme limite normale de tentatives. Si vous précisez les deux, décidez si la règle principale est l’échéance temporelle ou la limite en nombre, et figez cette intention avec des tests. MaxExceptions s’applique indépendamment de l’une et de l’autre.

Ordre de priorité des paramètres

Lorsque vous mélangez des paramètres du job et du worker, l’ordre de priorité suivant facilite les décisions. Lorsqu’une échéance définie par retryUntil ou RetryFor existe, le worker la fait primer sur le nombre de tries. Si vous utilisez RetryFor et retryUntil() ensemble, c’est le retryUntil() dynamique qui l’emporte.

Comment choisir

  • Si l’échéance d’attente du rétablissement d’un service externe est claire, utilisez RetryFor. Si elle est déterminée à l’exécution, utilisez retryUntil().
  • Pour les limites de débit d’une API ou la vérification de l’état d’un paiement, utilisez Backoff et releaseUsingBackoff().
  • Pour tolérer de nombreuses attentes temporaires de verrou mais peu d’exceptions réelles, combinez Tries et MaxExceptions.
  • Pour les traitements où les nouvelles tentatives cumulent des effets de bord, concevez non seulement le nombre de tentatives, mais aussi l’idempotence et le contrôle des doublons côté API externe.
Vous pouvez aussi préciser Tries et RetryFor sur les listeners d’événements et les notifications mis en file. Vérifiez que le payload de la cible utilisée porte le même contrat de nouvelle tentative.

Liens de référence

Dernière modification le 16 novembre 2026