Plánované prechody a sweep

Naplánujte prechod na konkrétny okamih; sweep ho spustí ako systém:

// The transition must be allowSystem() (or systemOnly() and scheduled with asSystem()).
$scheduled = Lifecycles::for($listing)->by($editor)->because('Launch')->schedule('publish', $publishAt);
Lifecycles::for($listing)->asSystem()->schedule('expire', $at);   // a systemOnly() transition

Lifecycles::for($listing)->scheduled();                 // list<ScheduledTransition>
Lifecycles::for($listing)->cancelScheduled('publish');  // bool
Lifecycles::for($listing)->retryScheduled('publish');   // bool: this listing's newest failed one, back to pending

Plánovanie overí štruktúru, zmrazenie a zapečatenie, pravidlá pre aktéra, dôvod a payload hneď, voči uloženému stavu; časové pravidlá, kvóty a rate limity sa overia pri spustení. Zamietnutie vyhodí TransitionDeniedException. Používateľ, ktorý plánuje prechod so systemOnly(), dostane zamietnutie system_only a prechod, ktorý označí kľúč zo sensitive() ako povinný, sa naplánovať nedá (invalid_payload), pretože plány citlivé kľúče nikdy neukladajú. Na jeden prechod existuje jeden čakajúci plán (a jedna expirácia) a opätovné naplánovanie ho nahradí. Odchod zo stavu, v ktorom plán vznikol, ho zruší.

Sweep

php artisan lifecycle:sweep (každú minútu) pošle splatné upozornenia a potom spúšťa splatné plány v dávkach, každý vo vlastnej transakcii, v systémovom kontexte:

• Zamietnutie z dočasných dôvodov: opakuje sa po schedules.retry_after (alebo keď to určí zamietnutie), najviac schedules.max_attempts-krát, potom failed. Trvalé zamietnutie zlyhá hneď. Oba prípady odošlú ScheduledTransitionFailed.
• Zmrazený subjekt: odloží sa bez spotrebovania pokusu.
• Soft-deleted subjekt: jeho plány sa pozastavia, kým sa neobnoví (obnovenie bez udalostí modelu, napríklad restoreQuietly(), zachytí najbližší sweep). Zmazaný subjekt svoje plány zruší.
• Výnimka: nahlási sa vášmu exception handleru a započíta ako pokus. Zvyšok sweepu pokračuje. Aj upozornenie, ktoré vyhodí výnimku, sa nahlási a sweep nikdy nezastaví; upozornenie, ktorého model, cyklus alebo stav už neexistuje, sa prestane posielať.

Lifecycles::sweep();                                  // SweepResult: warned, executed, deferred, failed, errored, cancelled, skipped, queued
Lifecycles::sweep(limit: 100, queue: true);           // dispatch RunScheduledTransitionJob per schedule
Lifecycles::schedules()->runDue();                    // due schedules only
Lifecycles::schedules()->warn();                      // warnings only
Lifecycles::schedules()->due();                       // Collection<ScheduledTransition>, read-only
Lifecycles::schedules()->failed();                    // Collection<ScheduledTransition>, most recently failed first
Lifecycles::schedules()->retry($scheduleId);          // failed → pending, attempts reset
Lifecycles::sweep(connection: 'tenant');              // the package tables of another connection

SweepResult počíta warned, executed, deferred, failed, errored, cancelled, skipped a queued, plus total(). „Teraz“ sú vždy hodiny — sweep „k budúcemu okamihu“ spustiť nejde; v testoch sa v čase posúvajte cez Carbon::setTestNow().

Databázové pripojenia

Riadky balíka sú na pripojení svojho subjektu a jeden sweep spracuje tabuľky balíka jedného pripojenia: predvoleného alebo toho, ktoré určíte cez lifecycle:sweep --database=<pripojenie>, Lifecycles::sweep(connection: …) či SweepOptions::$connection. Naplánujte jeden sweep pre každé pripojenie, ktoré vaše subjekty používajú — lifecycle:validate upozorní na uvedený model, ktorého pripojenie sweep nemá. Id plánov platia v rámci pripojenia: odovzdajte ho do schedules()->retry($id, $connection), kým retryScheduled() na handli použije pripojenie svojho subjektu.

Zlyhané plány

ScheduledTransition uvádza, ku ktorému subjektu patrí (subjectType, subjectId), a po dokončení aj to, ako skončil (status, outcome, lastDenial, finishedAt). schedules()->failed() vypíše zlyhané plány; jeden zopakujete podľa id cez schedules()->retry() alebo pre subjekt cez retryScheduled() — expirácia sa opakuje podľa názvu jej expiračného prechodu (retryScheduled('expire')). Ak chcete vedieť, kedy to plán vzdá, počúvajte ScheduledTransitionFailed:

use Illuminate\Support\Facades\Event;
use Illuminate\Support\Facades\Log;
use RoundlyConsulting\Lifecycle\Events\ScheduledTransitionFailed;

Event::listen(function (ScheduledTransitionFailed $event): void {
    Log::warning('Scheduled transition failed', ['schedule' => $event->scheduleId, 'transition' => $event->transition]);
});

Sweep cez frontu

S --queue, queue: true alebo schedules.queue.enabled sweep odošle jeden RunScheduledTransitionJob na každý splatný plán na schedules.queue.connection / schedules.queue.name. Každý plán dostane jeden unikátny job, aj keď sa fronta medzi sweepmi zasekne, a job všetko znova overí pod zámkom — opakovania aj zlyhania sa počítajú rovnako ako pri priamom behu.