Udalosti

Balík je bezstavový, takže prechody sám nezachytí — aktuálny stav však ohlási, keď oň požiadate. Zavolajte record() vo vlastnom kontrolnom bode a balík odošle StepCompleted pre každý dokončený viditeľný krok a FlowCompleted, keď je dokončený celý tok. Čítanie nikdy nič neodosiela; robí to len record().

use Illuminate\Support\Facades\Event;
use RoundlyConsulting\Onboarding\Events\FlowCompleted;
use RoundlyConsulting\Onboarding\Events\StepCompleted;
use RoundlyConsulting\Onboarding\Facades\Onboarding;

Onboarding::for($user)?->record();   // announce every complete step (+ FlowCompleted when done)
$user->onboarding()?->record();      // the same through the trait

Ak odovzdáte kľúč kroku, ohlási sa len tento krok, pokiaľ je viditeľný a dokončený. FlowCompleted odošle len vtedy, keď jeho dokončením skončil celý tok — krok je povinný, bol ohlásený (store ho ešte nemá zaznamenaný) a tok je teraz dokončený. Neznámy, nedokončený alebo voliteľný krok ju nespustí nikdy:

Onboarding::for($user)?->record('upload-photo');   // announce just one step

Obsah udalostí

Obe udalosti sú v RoundlyConsulting\Onboarding\Events a nesú naviazaný subjekt v $for — Model, akýkoľvek Authenticatable alebo null.

Počúvanie udalostí

Event::listen(StepCompleted::class, function (StepCompleted $e): void {
    // $e->step (Step), $e->for (the subject — Model, Authenticatable or null)
});

Event::listen(FlowCompleted::class, function (FlowCompleted $e): void {
    // $e->flow (Flow), $e->for (the subject)
});

Synchrónne a idempotentné listenery

Obe udalosti nesú živý objekt Step alebo Flow s closures — logikou dokončenia a vylúčenia —, preto sa nedajú serializovať. Listener s rozhraním ShouldQueue spôsobí, že record() vyhodí výnimku (Serialization of 'Closure' is not allowed), a to aj pri fronte sync. Ak potrebujete prácu vo fronte, počúvajte synchrónne a odošlite vlastný job s údajmi, ktoré potrebuje:

Event::listen(StepCompleted::class, function (StepCompleted $e): void {
    SyncOnboardingProgress::dispatch($e->step->stepKey(), $e->for); // your job, SerializesModels
});

Listenery musia byť aj idempotentné. Naviazaný store síce potlačí kroky, ktoré už vykazuje ako dokončené, táto kontrola však nie je atomická: dve súbežné volania record(), ktoré prebehnú skôr, než listener dokončenie uloží, ho ohlásia obe. Dokončenia preto zapisujte tak, aby druhé ohlásenie nič nepokazilo — unikátnym indexom na subjekt a kľúč kroku s insertOrIgnore() alebo cez firstOrCreate().

Kontrolný bod v kontroléri

public function update(Request $request): RedirectResponse
{
    $request->user()->update([
        'avatar_path' => $request->file('photo')->store('avatars'),
    ]);

    // a checkpoint of your choosing: announce the step this request may have completed
    Onboarding::for($request->user())?->record('upload-photo');

    return back();
}

Bez store každé volanie record() znova ohlási všetky dokončené kroky. Zapojte store cez Onboarding::useStore() a kroky, ktoré už vykazuje ako dokončené, sa znova neohlásia — pozrite si Perzistencia.