Laravel 13.31 voegt onderbreekbare jobs toe, waardoor queue workers het SIGTERM-signaal kunnen opvangen dat tijdens deployments wordt verzonden, om vervolgens netjes af te sluiten in plaats van een taak halverwege af te breken. Teams die lange jobs draaien — het verwerken van tienduizenden rijen, het verzenden van bulk-e-mails of het genereren van rapporten — profiteren hiervan omdat de gegevens consistent blijven wanneer een nieuwe release wordt uitgerold.

Waarom deployments jobs hebben afgebroken

Wanneer een nieuwe versie wordt geïnstalleerd, vertellen procesbeheerders zoals Supervisor, Docker en Kubernetes de bestaande workers om te stoppen door SIGTERM te verzenden, een beleefd verzoek om te beëindigen. De meeste workers wachten tot de huidige job is voltooid voordat ze afsluiten. Het probleem ontstaat wanneer de beheerder slechts enkele seconden de tijd geeft om te voldoen. Als een job minuten nodig heeft, escaleert de beheerder naar SIGKILL, waarmee het proces onmiddellijk wordt beëindigd. De job bereikt nooit een consistente staat, wat resulteert in gedeeltelijk bijgewerkte records, achtergebleven bestanden of dubbel werk.

Laravel’s antwoord: coöperatieve onderbreking

Laravel 13.31 introduceert een contract genaamd Interruptible dat een job-class kan implementeren om op de hoogte te zijn van het beëindigingsverzoek. Wanneer SIGTERM arriveert, roept Laravel de interrupted()-methode van de job aan. Het framework stopt de job niet automatisch; de job moet zelf een flag controleren die Laravel instelt en vervolgens zelfstandig afsluiten. Dit coöperatieve model stelt ontwikkelaars in staat om de huidige iteratie van een loop af te maken, gedeeltelijke wijzigingen terug te draaien of een checkpoint te schrijven voordat ze stoppen.

Hoe je een job onderbreekbaar maakt

  1. Implementeer het contract – voeg implements Interruptible toe aan de definitie van de job-class.
  2. Controleer de flag binnen de werkloop – voeg bij elke iteratie een controle toe om te zien of de job moet stoppen.
  3. Voer schoonmaakwerkzaamheden uit – bewaar in interrupted() de status die de job later mogelijk kan hervatten, of log de onderbreking voor latere analyse.

De grootste valkuil: gebruik --once niet

Het draaien van de queue worker met php artisan queue:work --once schakelt de signaalafhandeling volledig uit. De worker verwerkt een enkele job en sluit af, maar registreert nooit de SIGTERM-handler. Hierdoor negeert elke onderbreekbare job het beëindigingsverzoek en wordt deze halverwege het proces gedood. Dit patroon komt voor in cron-gestuurde containers en one-shot deployments. Los dit op door de daemon-modus (php artisan queue:work) te gebruiken wanneer je onderbreekbare jobs nodig hebt.

Toezien op onderbrekingen

Laravel vuurt twee events af waaraan je kunt koppelen:

  • WorkerInterrupted – wordt uitgezonden telkens wanneer een worker een SIGTERM ontvangt. Het loggen van dit event geeft een overzicht van hoe vaak deployments workers onderbreken.
  • JobInterrupted – wordt alleen uitgezonden als de huidige job het Interruptible-contract implementeert. Gebruik dit event om job-specifieke schoonmaakwerkzaamheden uit te voeren, zoals het verwijderen van tijdelijke bestanden of het bijwerken van een "laatst verwerkte rij"-marker.

Door naar deze events te luisteren, kunnen teams dashboards bouwen die de impact van deployments laten zien en jobs opsporen die regelmatig voortijdig worden afgebroken.

Rapportage van de queue-grootte krijgt een aanpassing

De release voegt een totalSize()-methode toe aan de queue manager, die het totale aantal openstaande jobs in alle queues retourneert. De waarde is betrouwbaar voor op een database gebaseerde en Redis-drivers, die werkelijke aantallen rapporteren. Drivers zoals SQS, Sync en Beanstalkd retourneren nog steeds nul omdat ze geen aantal via de API van Laravel blootstellen. Teams die SQS gebruiken, moeten blijven vertrouwen op CloudWatch-metrieken voor de queue-diepte.

Wat dit betekent voor verschillende omgevingen

  • Docker/Kubernetes – de periode voor een gecontroleerde shutdown kan nu effectief worden gebruikt. Vergroot de termination grace period zodat jobs enkele seconden de tijd hebben om de flag op te merken en netjes af te sluiten.
  • Supervisor – stel stopwaitsecs hoger in dan de tijd die je verwacht dat een job nodig heeft om af te ronden nadat de interrupt-flag is ontvangen.
  • Legacy jobs – bekijk elke job die langer draait dan de timeout van de beheerder en maak deze, waar mogelijk, onderbreekbaar.

Tegenargument: extra complexiteit

De functie vervangt geen correcte timeout-configuratie. Als de loop van een job de onderbrekingsflag nooit controleert, zal de beheerder nog steeds SIGKILL verzenden. Teams moeten langlopende codepaden controleren en checks invoegen op logische breekpunten. Sommige ontwikkelaars vinden de extra boilerplate — het implementeren van een contract en het toevoegen van flag-controles — misschien niet aantrekkelijk voor korte jobs die toch al binnen het shutdown-venster klaar zijn.

Actiechecklist

  1. Scan deploymentscripts op de --once-vlag en vervang deze door daemon mode waar interruptible jobs worden gebruikt.
  2. Identificeer de langstlopende jobs (die tienduizenden rijen verwerken of enkele minuten draaien) en voeg het Interruptible contract toe.
  3. Voeg een flag-check toe binnen elke loop-iteratie en verplaats eventuele noodzakelijke afsluitcode naar de interrupted()-methode.
  4. Koppel listeners aan WorkerInterrupted en JobInterrupted om metrics te verzamelen over hoe vaak deployments de verwerking beïnvloeden.
  5. Gebruik voor Redis- of database-queues totalSize() om de backlog te monitoren; houd voor SQS de CloudWatch-alarms in stand.

Behandel door deployments veroorzaakte shutdowns als een gecoördineerde stap in plaats van een abrupte stop. Laravel 13.31 houdt data consistent en vermindert de operationele hoofdpijn van half-voltooide jobs. Het nadeel is een bescheiden toename in verantwoordelijkheid voor de code, maar teams die afhankelijk zijn van zware achtergrondverwerking krijgen een betrouwbaardere productieomgeving.