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

• Brian Faust
• All Contributors

License

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