README

Lifecycle for Laravel

Status lifecycles for any Eloquent model — orders, tickets, listings, subscriptions. Named transitions behind one guard pipeline, race-free quotas, expiry and scheduled transitions, rollbacks and an append-only history.

Installation

Requires PHP 8.4, Laravel 12 or 13, and SQLite, PostgreSQL or MySQL/MariaDB.

composer require roundly-consulting/lifecycle-for-laravel
php artisan vendor:publish --tag="lifecycle-migrations"
php artisan migrate

If your models or users have UUID/ULID keys, set LIFECYCLE_KEY_TYPE / LIFECYCLE_ACTOR_KEY_TYPE before migrating. States with a TTL need the sweep scheduled: Schedule::command('lifecycle:sweep')->everyMinute();.

Usage

Define the lifecycle once (php artisan make:lifecycle ListingLifecycle generates the class):

use RoundlyConsulting\Lifecycle\Definition\LifecycleBuilder;
use RoundlyConsulting\Lifecycle\Definition\LifecycleDefinition;

final class ListingLifecycle extends LifecycleDefinition
{
    public function define(LifecycleBuilder $lifecycle): void
    {
        $lifecycle->states(ListingStatus::class)   // a backed enum: draft, active, closed, expired
            ->initial(ListingStatus::Draft);

        $lifecycle->state(ListingStatus::Active)
            ->ttl('30 days')->expiresVia('expire')
            ->quota(5, scope: 'user_id');           // at most 5 active listings per user

        $lifecycle->transition('publish')->from(ListingStatus::Draft)->to(ListingStatus::Active)->ability('publish');
        $lifecycle->transition('close')->from(ListingStatus::Active)->to(ListingStatus::Closed)->requiresReason();
        $lifecycle->transition('expire')->from(ListingStatus::Active)->to(ListingStatus::Expired)->systemOnly();
    }
}

Attach it to the model:

use RoundlyConsulting\Lifecycle\Concerns\HasLifecycle;
use RoundlyConsulting\Lifecycle\Contracts\LifecycleSubject;

final class Listing extends Model implements LifecycleSubject
{
    use HasLifecycle;

    public function lifecycleDefinitions(): array
    {
        return ['status' => ListingLifecycle::class];
    }

    protected function casts(): array
    {
        return ['status' => ListingStatus::class];
    }
}

Then move it through its states:

use RoundlyConsulting\Lifecycle\Facades\Lifecycles;

Lifecycles::for($listing)->by($user)->apply('publish');      // draft → active, checked by the Gate

Lifecycles::for($listing)->can('close');                     // true
Lifecycles::for($listing)->because('Sold elsewhere')->apply('close');

Lifecycles::for($listing)->rollback();                       // undo the last transition
Lifecycles::for($listing)->history();                        // who did what, when and why

Documentation

The full documentation — configuration, every feature and its API, and testing — lives on our website: roundly-consulting.com/open-source/docs/lifecycle-for-laravel

Release notes are in CHANGELOG.md. To contribute, see the contributing guide.

Support our work

This package is free and open source, built and maintained by Roundly Consulting. If it saves you time, please consider supporting our open-source work — a one-time donation, a monthly pledge on Patreon or a crypto donation helps fund maintenance, new features and new packages.

License

The MIT License (MIT). See LICENSE.md.

roundly-consulting / lifecycle-for-laravel

Package info

Security

Fund package maintenance!

Statistics