Events

Listen for LifecycleTransitioned rather than Eloquent’s updated: the state write is a direct compare-and-swap, so model events do not fire for it. It covers every state change — transitions, expiries, scheduled runs, rollback steps and adoptions — but not creation, where your model’s created event and the initial history row are the signal:

use Illuminate\Support\Facades\Event;
use RoundlyConsulting\Lifecycle\Enums\TransitionKind;
use RoundlyConsulting\Lifecycle\Events\LifecycleTransitioned;

Event::listen(function (LifecycleTransitioned $event): void {
    if ($event->subject instanceof Listing && $event->to === ListingStatus::Active) {
        SearchIndex::add($event->subject);
    }

    if ($event->kind === TransitionKind::Rollback) {
        AuditLog::record("Rolled back to {$event->to->value}", $event->historyId);
    }
});

• LifecycleTransitioning runs inside the transaction; a throwing listener aborts and rolls everything back, but denials belong in guards. A deadlock retry runs it again.
• LifecycleTransitionDenied is deliberately not after-commit — it fires even when your own outer transaction then rolls back because of the denial.
• After-commit events inside your own transaction are held until your outermost transaction commits, and discarded if it rolls back.
• Payloads never contain the transition payload. Read the history row (historyId) when you need the stored, validated context.
• Queued listeners should re-fetch the subject by subjectType / subjectId.
• Idempotent replays and Lifecycles::fake() fire nothing.