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.
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.
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.
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’attributBackoff ou la méthode backoff().
Intervalle fixe
backoff(). backoff() prime sur l’attribut Backoff.
--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 », utilisezreleaseUsingBackoff(). 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.
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é.
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.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, utilisezretryUntil(). - Pour les limites de débit d’une API ou la vérification de l’état d’un paiement, utilisez
BackoffetreleaseUsingBackoff(). - Pour tolérer de nombreuses attentes temporaires de verrou mais peu d’exceptions réelles, combinez
TriesetMaxExceptions. - 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
- Documentation officielle de Laravel : Max job attempts and timeout
- Documentation officielle de Laravel : Time-based attempts
- Documentation officielle de Laravel : Libération manuelle et
releaseUsingBackoff - Documentation officielle de Laravel : Backoff des jobs échoués
- Attribut
RetryFor - Attributs
Backoff,TriesetMaxExceptions Queue::getJobExpirationInteractsWithQueue::releaseUsingBackoff