Weave Code
Lifecycle For Laravel Laravel Package
roundly-consulting/lifecycle-for-laravel
Lifecycle for Laravel adds configurable lifecycles to Eloquent models: define states, allowed transitions, guards, and hooks so business rules stay organized, predictable, and testable instead of scattered across controllers, observers, and service classes.
Status lifecycles for Eloquent models: guarded named transitions, limits and quotas, expiry and scheduled transitions, rollbacks and an append-only history.
Frequently asked questions about Lifecycle For Laravel
- How do I install roundly-consulting/lifecycle-for-laravel in a Laravel app?
- Install it with Composer using composer require roundly-consulting/lifecycle-for-laravel. The default behavior works with zero configuration, so you can start defining states and transitions for an Eloquent model immediately. Publish the package config only when you need to customize keys such as the actor resource used by history endpoints.
- Which Laravel and PHP versions does Lifecycle for Laravel support?
- The runtime Laravel and PHP constraints are declared in the package composer.json, so check that file and the release notes before upgrading. The bump to ^1.6 mentioned in the package assessment is a dev-only testing dependency change and does not by itself signal a new supported Laravel or PHP matrix. Verify the matrix against the specific release you intend to install rather than assuming minor releases keep identical requirements.
- How do I define states and allowed transitions for an Eloquent model?
- You define states and the named transitions allowed between them in the package lifecycle configuration for each model. The package then enforces those transitions at runtime, so invalid state changes are rejected instead of being reimplemented across controllers, observers, and service classes. Guarded named transitions also keep the rules in one place, which makes them easier to reason about and test.
- What are guards and hooks in a lifecycle, and when should I use them?
- Guards decide whether a named transition is permitted, letting you encode business rules that must hold before a state change. Hooks let you attach behavior around a transition so side effects and validation stay tied to the lifecycle definition. Using both keeps logic out of controllers and service classes and makes transitions predictable and testable.
- Can I enforce limits and quotas on model transitions?
- Yes, the package includes limits and quotas as part of its lifecycle features, so you can cap how often or how many transitions occur. Those constraints live in the lifecycle definition instead of being scattered through application code. That keeps quota behavior consistent across every code path that triggers a transition.
- How do expiry and scheduled transitions work in this package?
- Expiry and scheduled transitions are part of the lifecycle feature set, so time-based state changes are declared alongside your other transition rules. Release 1.1.0 introduces no queue, cache, or external service, so the package composes with the scheduling you already run in your application. Check the README for the exact configuration keys and how scheduled transitions are triggered.
- Does the package keep a history of transitions, and can I roll a model back?
- Yes. The package maintains an append-only transition history with polymorphic actor attribution and supports rollbacks. History is exposed through Eloquent API Resources, and in 1.1.0 the packaged resource renders history rows without touching the actor table. That keeps history endpoints cheap as long as you do not add a custom resource that loads actor attributes.
- How do I test lifecycle transitions in my Laravel test suite?
- Because rules are defined in configuration and enforced by the package, you can write feature tests that assert a transition succeeds or is blocked and then inspect the append-only history. Snapshot tests of the JSON returned by history endpoints are the most reliable way to catch consumer-visible changes such as the actor.type derivation in 1.1.0. Run those snapshots in a non-production environment before upgrading and diff the fixtures.
- Why did actor.type change in 1.1.0, and is it a breaking change?
- In 1.1.0 the actor.type value, and last_transition.actor.type with it, derives from the class basename rather than the morph class, so App\Models\User becomes User and a morph-map alias such as user also becomes User. That silently changes the wire contract for any client, OpenAPI schema, TypeScript enum, webhook consumer, or snapshot test keyed on type. Treat it as breaking for API consumers regardless of the minor version number. Inventory consumers, upgrade in a non-production environment, diff JSON fixtures, and consider a compatibility resource that emits the old morph-class value until clients roll over.
- When is lifecycle.resources.actor resolved and validated, and can a custom actor resource cause N+1 queries?
- InvalidLifecycleConfigurationException::notAResource is thrown for values that are not instantiable or do not implement the JsonResource contract, but the exact timing, whether at boot, container resolution, or first history render, is not documented, so the worst case is a production 500 on a history endpoint rather than a deploy-time failure. The packaged TransitionActorResource wraps the TransitionRecord and loads no actor, so it avoids N+1 queries. A custom actor resource that adds name or avatar will lazy-load per row unless actors are eager-loaded, so record the resources.actor key explicitly and eager-load actors when you customize it.
Weaver
How can I help you explore Laravel packages today?