README

A flexible state management package for Laravel that allows any model or object to have multiple states with full transition history, context isolation, and environment support.

Features

Multiple States Per Object - Assign unlimited states to any context
Namespaced States - Organize states with optional namespaces (e.g., workflow.pending)
Context & Boundary Scoping - Isolate states by context and optional boundary
Environment Support - Separate states across environments (production, staging, etc.)
Full Transition History - Track every state change with actor, reason, and metadata
State Machine Validation - Configure allowed transitions per context type
Fluent API - Chainable conductor-based operations
100% Test Coverage - Comprehensive test suite with PHPStan max level

Requirements

Requires PHP 8.4+ and Laravel 11+

Installation

composer require cline/states

Publish the migration and run it:

php artisan vendor:publish --tag="states-migrations"
php artisan migrate

Optionally publish the config file:

php artisan vendor:publish --tag="states-config"

Quick Start

use Cline\States\Facades\States;

// Assign a state
$user = User::find(1);
States::for($user)->assign('active');

// Transition between states
States::for($user)
    ->by($admin)
    ->because('User completed onboarding')
    ->transition('pending', 'active');

// Check states
States::hasState($user, 'active'); // true

// Get all states
$states = States::getStates($user);

Documentation

Getting Started - Installation, configuration, and quick start
Basic Usage - Assigning, transitioning, and removing states
Contexts and Boundaries - Scoping states to specific contexts
Environments - Managing states across different environments
Transition History - Tracking and querying state changes
State Machines - Validating allowed transitions
Advanced Usage - Events, metadata, and advanced patterns
Configuration - Advanced configuration options

Change log

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING and CODE_OF_CONDUCT for details.

Security

If you discover any security related issues, please use the GitHub security reporting form rather than the issue queue.

Credits

License

The MIT License. Please see License File for more information.

cline / states

Maintainers

Details