Aplikovanie prechodov

Vytvorte handle s kontextom volania a aplikujte prechod podľa názvu — alebo podľa cieľového stavu:

use RoundlyConsulting\Lifecycle\Facades\Lifecycles;

// A handle per subject (and lifecycle), with the call's context
Lifecycles::for($listing)
    ->by($user)                         // the actor (default: the authenticated user)
    ->because('Back in stock')          // the reason, stored in history
    ->with(['note' => 'Restocked'])     // the payload, validated by the transition's rules()
    ->apply('reopen');

Lifecycles::for($listing)->transitionTo(ListingStatus::Closed);   // by target state
Lifecycles::for($listing)->asSystem()->apply('expire');            // system context

Skratka cez trait

$listing->transition('close', ['note' => 'Sold elsewhere']);   // name, payload, lifecycle
$listing->canTransition('reopen');                             // bool
$listing->lifecycle()->by($user)->because('Back in stock')->apply('reopen');
$listing->transitionTo(ListingStatus::Archived);

Výsledky a zamietnutia

apply() vráti TransitionResult (subject, lifecycle, transition, from, to, record, replayed). Zamietnuté volanie vyhodí TransitionDeniedException a model nechá presne taký, aký bol. attempt() zamietnutie vráti namiesto vyhodenia:

$attempt = Lifecycles::for($listing)->by($user)->attempt('close');

if (! $attempt->succeeded) {
    return back()->withErrors($attempt->decision->messages());
}

transitionTo() vyberie jediný prechod z aktuálneho stavu do cieľa. Ak žiadny neexistuje, volanie sa zamietne s no_transition_to_state; ak ich je viac, vyhodí AmbiguousTransitionException — vtedy zavolajte apply() s názvom.

Payload a dôvody

Payload validujú rules() prechodu a ku guardom, handlerom a do histórie sa dostanú len zvalidované kľúče — bez kľúčov zo sensitive(), ktoré sa nikdy neukladajú. Payload poslaný prechodu bez rules() vyhodí InvalidLifecycleUsageException, namiesto toho, aby sa potichu zahodil:

$lifecycle->transition('refund')
    ->from('captured')->to('refunded')
    ->requiresReason(5)
    ->rules(['amount' => 'required|integer|min:1', 'card_number' => 'nullable|string'])
    ->sensitive('card_number');

Lifecycles::for($payment)->because('Customer request')->with(['amount' => 500])->apply('refund');

Dĺžku dôvodu obmedzuje history.reason_max_length a uložený kontext history.max_context_bytes; s vypnutým history.store_payload sa payload neukladá vôbec.

Optimistické verzie

Každá zmena stavu zvýši verziu záznamu o jedna. Pošlite ju vo formulári alebo v odpovedi API a vráťte ju späť:

Lifecycles::for($listing)->version();                         // e.g. 4, sent to the client
Lifecycles::for($listing)->expectingVersion(4)->apply('close'); // refused with stale_version if it moved on

Idempotentné kľúče

Pre webhooky a opakované pokusy aplikuje idempotentný kľúč prechod najviac raz:

$result = Lifecycles::for($order)->idempotencyKey("payments:{$event->id}")->apply('pay');
$result->replayed;   // true when this key was already applied; nothing ran again

Opakovanie vráti pôvodný výsledok bez guardov, zápisov aj udalostí. Použitie kľúča pre iný prechod vyhodí IdempotencyConflictException. Opakovanie neoveruje pravidlá pre aktéra, preto používajte kľúče, ktoré sa nedajú uhádnuť alebo obsahujú aktéra.

Neuložené zmeny modelu

apply() po handleroch uloží model, ak má akékoľvek neuložené zmeny — vrátane tých, ktoré ste urobili pred volaním. Neuložená zmena samotného atribútu cyklu je chybou použitia, rovnako ako handler či hook, ktorý zmení práve zapisovaný stav. V handleroch si každý iný model (aj každý iný cyklus toho istého modelu) ponechá striktné zápisy: stav iného subjektu meňte prechodom. Ak čokoľvek vyhodí výnimku, všetko sa vráti vrátane modelu v pamäti — celú transakciu opisuje časť Handlery, hooky, stampy a snapshoty.

Soft-deleted subjekt vyhodí SubjectTrashedException a prechod do stavu s kvótou, ktorý by zároveň zmenil niektorý stĺpec scope tejto kvóty, vyhodí InvalidLifecycleUsageException — pozri Limity, kvóty a zmrazenie.