Lifecycle For Laravel Laravel Package

Product Decisions This Supports

• Public/partner API surface for audit and history data. TransitionRecordResource and LifecycleResource.last_transition now emit actor: {id, type}, so "who did this" is a stable, renderable field in our API without exposing PHP internals (App\Models\User). This unblocks shipping history/activity endpoints as a product feature rather than an internal debug view.
• Build vs. buy on audit trails. Actor rendering, morph/alias normalization (User, not App\Models\User, not the morph alias), and a swappable resource mean we do not write and maintain our own presenters for transition history. Buy the package; spend the sprint on our actor payload instead.
• Enriching actor display without touching the package. lifecycle.resources.actor lets us point at our own JsonResource to add a name, avatar, or email — a product-visible decision (does the timeline show a name or a user ID?) that is now a config value, not a fork.
• Performance budgeting for history screens. The actor resource wraps the TransitionRecord, so rendering history loads no actor and adds no query. That removes the usual N+1 risk before we commit to an unbounded or paginated audit feed — a real input to whether the feed can ship as-is or needs async/export treatment.
• Guardrails as a product-safety feature. A malformed lifecycle.resources.actor (blank string is treated as packaged default; a non-instantiable JsonResource throws InvalidLifecycleConfigurationException with notAResource) fails loudly at boot rather than silently degrading. That lowers the blast radius of a bad deploy on customer-facing history.

When to Consider This Package

Adopt when:

• We expose transition/state history to users, support, or partners, and need a consistent actor shape in API responses.
• Our domain already uses model state transitions (orders, tickets, approvals, subscriptions) and we want one history representation across resources rather than per-endpoint formatting.
• We run a morph map, or want to — the new behavior resolves type to the basename of the mapped class, so aliases do not leak either.
• We expect to customize actor payloads; the lifecycle.resources.actor swap and its validation give us that cheaply.

Look elsewhere or defer when:

• Contract stability is the priority right now. This release changes actor.type from morph class to class basename. Any consumer parsing the old value, including our own frontend or a partner integration, must be checked and versioned before we upgrade. Treat it as a breaking payload change and plan a coordinated rollout.
• We need actor enrichment immediately but cannot yet publish a custom JsonResource — until lifecycle.resources.actor points at ours, the API shows {id, type} only, which may be insufficient for a human-facing timeline.
• We need history semantics the package does not state it covers (retention policy, backfill of pre-existing rows, PII redaction in audit records). Those are our obligations regardless of package choice.
• We need multi-actor or team-level attribution beyond a single morph actor; verify the model fits before committing.

How to Pitch It (Stakeholders)

To executives: We can ship user-facing "who changed this and when" history using a maintained package instead of custom code. The cost is a small config change plus a review of what our API returns — not a build. One caveat: this release changes the actor type value our API emits, so we should sequence it as a deliberate API change rather than a routine bump.

To engineering: The release adds TransitionActorResource (renders {id, type} from the TransitionRecord, no actor load, no extra query) and a lifecycle.resources.actor config key accepting any instantiable JsonResource; blank or null keeps the packaged one, and invalid values throw InvalidLifecycleConfigurationException (notAResource) at configuration time. The actor.type output is now the actor class basename instead of the morph class, and with a morph map it is the basename of the mapped class rather than the alias — audit serializers, snapshots, and client parsers for dependency on the old string, and add a contract test pinning actor to {id, type}. Upgrade path: pin lifecycle.resources.actor, ship the resource swap and any payload change together, then verify query counts on the history endpoint remain flat. Also note the dev/CI maintenance items are non-functional.