Laravel StateFlow

A modern, enterprise-ready state machine implementation for Laravel Eloquent models.

Author: Hamed Panjeh

laravel-pay-pocket https://github.com/HPWebdeveloper/laravel-pay-pocket
laravel-failed-jobs https://github.com/HPWebdeveloper/laravel-failed-jobs
laravel-stateflow https://github.com/HPWebdeveloper/laravel-stateflow

Laravel StateFlow is inspired by similar concepts found in Spatie Laravel Model States, however, it is a fully independent, ground-up implementation with its own architecture and design decisions. It combines the state pattern with state machines to deliver enterprise-ready features: automatic state class discovery, automatic transition discovery, permissions, UI metadata, history tracking, and API resources. Laravel StateFlow maintains a single, unified topology of all possible states and transitions in your application's backing enum. This centralized architecture ensures that state definitions remain synchronized across your entire application, eliminating inconsistencies between backend logic and frontend representations. For large, complex systems, managing state changes and transitions is no longer cumbersome or bug-prone as your system grows—a single enum serves as the definitive source of truth.

📦 Demo Application: See Laravel StateFlow in action with a complete order management demo at laravel-stateflow-demo.

📚 Table of Contents

Introduction
Why Laravel StateFlow?
Installation
Preparation in 4 Simple Steps
How to Use It
Transitions
Permissions
History Tracking
API Resources
Query Scopes
Validation Rules
Events
Artisan Commands
Configuration Reference
Common Patterns
Version Compatibility
Credits
License

Introduction

This package adds state support to your Eloquent models. It lets you represent each state as a separate class, handles serialization to the database behind the scenes, and provides a clean API for state transitions with full authorization and audit capabilities.

Example: Imagine an Order model with states: Pending, Processing, Shipped, Delivered, and Cancelled. Each state can have its own color for UI, permitted roles for authorization, and the transitions between them are explicit and validated.

// Check the current state
$order->state->name();        // 'pending'
$order->state->color();       // 'yellow'

// Get available transitions for the current user
$order->getNextStates();      // [Processing::class, Cancelled::class]

// Perform a transition with full audit trail
$order->transitionTo(Processing::class, reason: 'Order confirmed by warehouse');

Why Laravel StateFlow?

The Problem: Manual State Management in Legacy Systems

In traditional Laravel applications, state management is typically handled with simple string columns and scattered conditional logic:

// Legacy approach — manual state management everywhere
if ($order->status === 'pending') {
    $order->update(['status' => 'processing']);
}

😐 Now answer these questions:
// 1. What states can this order transition to RIGHT NOW?
// 2. What buttons should I show the user in the UI?
// 3. Which users are ALLOWED to perform each transition?
// 4. Where is my complete workflow defined? (Check 10+ files?)
// 5. What's the audit trail for this state change?
// 6. How do I prevent invalid transitions like pending → shipped?
// 7. How do I store a reason or note explaining WHY this transition happened?
// 8. How do I query all orders "stuck" in a specific state?
// 9. What color/icon should represent each state in the UI?
// 10. How do I serialize state data consistently for my API/SPA?
// 11. How do I fire events when specific transitions occur?
// 12. How do I rollback or revert to a previous state if needed?

🤦‍♂️ This creates several pain points:

Scattered Workflow Definition

Transitions defined across multiple files — no single source of truth
To understand your workflow, you must open every file and mentally piece together the graph
Refactoring is risky — changing one state might break transitions you forgot about
No way to export or visualize the complete workflow as a diagram
State dependencies are implicit — you discover them only when something breaks

Frontend/Backend Synchronization Gap

Views must hardcode which buttons to show for each state
No built-in way to query available transitions from current state
UI metadata (colors, icons, labels) lives outside the state machine
State labels must be duplicated in frontend code — prone to drift
No TypeScript types generated for frontend consumption
No way to get human-readable names or descriptions from backend

Missing Enterprise Features

No permission system — you build authorization logic from scratch
No audit trail — state changes vanish without history tracking
No API resources — serializing states for SPAs requires manual work
No transition metadata — who can perform it, what requirements exist
No way to attach context to transitions (reasons, notes, actor info)
No guards for complex conditional transition logic
No hooks for state-specific business logic (entering/exiting a state)

Data & Querying Limitations

No efficient scopes to query models by current state
No way to find models "stuck" in certain states for too long
State history not queryable — cannot analyze transition patterns
No reversion capability — cannot rollback to a previous state

Testing & Maintenance Burden

Hard to visualize complete state flow without documentation
Difficult to test all transition paths systematically
State machine grows silently complex as features are added
Cannot programmatically list all possible transition paths
Documentation drifts from actual code — no single source of truth
No IDE support for navigating from state to its allowed transitions

Laravel-StateFlow's Solution: Centralized State Topology

StateFlow supports two approaches for defining your state machine:

Approach	Best For	Transitions Defined In
Traditional	Self-contained states, IDE navigation	State classes or model
Hybrid Enum	Centralized workflow visualization	Single enum file

Both approaches are demonstrated in the laravel-stateflow-demo: Orders (traditional) and Bookings (enum).

Laravel StateFlow solves this with centralized workflow definition — see your entire state machine at a glance:

// 📋 app/Enums/BookingStateStatus.php — Complete topology in ONE place!
enum BookingStateStatus: string
{
    case Draft = 'draft';
    case Confirmed = 'confirmed';
    case Paid = 'paid';
    case Fulfilled = 'fulfilled';
    case Cancelled = 'cancelled';

    public function canTransitionTo(): array
    {
        return match ($this) {
            self::Draft     => [Confirmed::class],
            self::Confirmed => [Paid::class, Cancelled::class],
            self::Paid      => [Fulfilled::class, Cancelled::class],
            self::Fulfilled, self::Cancelled => [], // Final states
        };
    }
}

// 🎯 app/Models/Booking.php — Clean, 3-line configuration!
class Booking extends Model implements HasStatesContract
{
    use HasStates;

    public static function registerStates(): void
    {
        static::addState('state', StateConfig::make(BookingState::class)
            ->default(Draft::class)
            ->registerStates(BookingStateStatus::stateClasses())
            ->allowTransitionsFromArray(BookingStateStatus::transitions())
        );
    }
}

💡 See it live: BookingStateStatus.php ・ Booking.php ・ Docs

⭐️⭐️⭐️⭐️⭐️ Key Innovations

Laravel StateFlow provides enterprise features like automatic state discovery, rich UI metadata, built-in permissions, complete audit trails, and seamless Eloquent integration:

Feature	✓	Description	Example
Generate enum from states	✅	Create workflow enum from existing state classes	`php artisan stateflow:sync-enum` ・ Docs
Automatic next states	✅	Discover available transitions from current state	OrderController.php ・ Docs
UI metadata	✅	Colors, icons, titles for frontend integration	Pending.php ・ Docs
Eloquent integration	✅	Cast-based approach with clean, Laravel-native syntax	Order.php
Role-based permissions	✅	Control transitions by user roles	Processing.php ・ Docs
Policy-based permissions	✅	Use Laravel policies for transition authorization	OrderPolicy.php ・ Docs
State history & audit	✅	Complete transition history with performer tracking	OrderController.php#show ・ Docs
API Resources	✅	Ready-to-use JSON responses for states	Docs
Advanced query scopes	✅	`orderByState`, `countByState`, `averageTimeInState`	Docs
Silent transitions	✅	Transition without firing events	Docs
Force transitions	✅	Bypass validation for admin overrides	Docs
Fluent transition API	✅	Clean, chainable API for transitions	Docs
Centralized enum transitions	✅	Define state topology in a single enum for clarity	BookingStateStatus.php ・ Docs

Installation

composer require hpwebdeveloper/laravel-stateflow

Publish the config (optional):

php artisan vendor:publish --tag="laravel-stateflow-config"

For history tracking, publish and run migrations:

php artisan vendor:publish --tag="laravel-stateflow-migrations"
php artisan migrate

Preparation in 4 simple Steps

1. Add State Column to Your Model

Add a state column to the model that will have state transitions. For example, if you have an Order model:

// In a migration file
Schema::table('orders', function (Blueprint $table) {
    $table->string('state')->default('pending');
});

Note: Replace orders with your table name (e.g., posts, invoices, tickets).

2. Create State Classes

Generate all state classes at once using the --states option:

php artisan make:state OrderState --states=Pending,Processing,Shipped,Delivered,Cancelled

This single command creates the base class and all extending state classes:

app/States/
  ├── OrderState.php      # Abstract base class
  ├── Pending.php
  ├── Processing.php
  ├── Shipped.php
  ├── Delivered.php
  └── Cancelled.php

Alternative: You can also create states individually:

php artisan make:state OrderState --base
php artisan make:state Pending --extends=OrderState
php artisan make:state Processing --extends=OrderState
# ... and so on

💡 See the demo: The laravel-stateflow-demo uses this structure — see States/Order/ for a complete example.

⚠️ Important: Keep all state classes in the same directory as their base state class. When adding new states later, use the full namespace:
php artisan make:state Processing --extends=App\\States\\Booking\\BookingState
The stateflow:sync-enum command only discovers states in the same directory as the base class.

3. Configure States

3.1 Traditional Approach — State Classes with Metadata

StateFlow supports multiple approaches for defining state metadata: Methods, Attributes, and Constants. The demo uses a combined approach — attributes for static metadata (title, description) and methods for dynamic values (color(), icon()).

// app/States/Order/Pending.php
use Hpwebdeveloper\LaravelStateflow\Attributes\DefaultState;
use Hpwebdeveloper\LaravelStateflow\Attributes\StateMetadata;
use Hpwebdeveloper\LaravelStateflow\Attributes\AllowTransition;

#[DefaultState]
#[StateMetadata(title: 'Pending', description: 'Order is pending confirmation')]
#[AllowTransition(to: Processing::class)]
#[AllowTransition(to: Cancelled::class)]
class Pending extends OrderState
{
    public const NAME = 'pending';

    public static function color(): string { return 'yellow'; }
    public static function icon(): string { return 'clock'; }
}

💡 See the demo: Pending.php and States/Order/

3.2 Hybrid Enum Approach — Centralized Workflow Topology

For teams who prefer seeing the entire workflow at a glance, use an enum to define the transition topology. State classes still handle behavior (colors, icons, metadata).

# Create states with enum scaffold
php artisan make:state BookingState --states=Draft,Confirmed,Paid,Fulfilled,Cancelled,Expired --transitions=enum

The Enum — Shows all transitions in one place:

// app/Enums/BookingStateStatus.php
enum BookingStateStatus: string
{
    case Draft = 'draft';
    case Confirmed = 'confirmed';
    case Paid = 'paid';
    case Fulfilled = 'fulfilled';
    case Cancelled = 'cancelled';
    case Expired = 'expired';

    /**
     * 📋 Complete workflow topology at a glance!
     */
    public function canTransitionTo(): array
    {
        return match ($this) {
            self::Draft     => [Confirmed::class, Expired::class],
            self::Confirmed => [Paid::class, Cancelled::class, Expired::class],
            self::Paid      => [Fulfilled::class, Cancelled::class],
            // Final states — no transitions
            self::Fulfilled, self::Cancelled, self::Expired => [],
        };
    }

    public function stateClass(): string { /* maps to state class */ }
    public static function stateClasses(): array { /* all state classes */ }
    public static function transitions(): array { /* for StateConfig */ }
}

State classes remain simple (behavior only, no transitions):

// app/States/Booking/Draft.php
#[DefaultState]
#[StateMetadata(title: 'Draft', description: 'Booking in draft')]
class Draft extends BookingState
{
    public const NAME = 'draft';
    public static function color(): string { return 'gray'; }
}

💡 See the demo: BookingStateStatus.php and States/Booking/

📚 Learn more: See Defining States and Transitions for detailed comparison of all approaches.

4. Add to Model

4.1 Traditional Approach — Explicit Transitions

use Hpwebdeveloper\LaravelStateflow\HasStates;
use Hpwebdeveloper\LaravelStateflow\HasStatesContract;
use Hpwebdeveloper\LaravelStateflow\StateConfig;

class Order extends Model implements HasStatesContract
{
    use HasStates;

    public static function registerStates(): void
    {
        static::addState('state', StateConfig::make(OrderState::class)
            ->default(Pending::class)
            ->registerStates([
                Pending::class,
                Processing::class,
                Shipped::class,
                Delivered::class,
                Cancelled::class,
            ])
            ->allowTransition(Pending::class, Processing::class)
            ->allowTransition(Pending::class, Cancelled::class)
            ->allowTransition(Processing::class, Shipped::class)
            ->allowTransition(Processing::class, Cancelled::class)
            ->allowTransition(Shipped::class, Delivered::class)
        );
    }
}

💡 See the demo: Order.php

4.2 Hybrid Enum Approach — Clean & Elegant ✨

With the enum approach, your model becomes remarkably clean:

use App\Enums\BookingStateStatus;
use App\States\Booking\{BookingState, Draft};

class Booking extends Model implements HasStatesContract
{
    use HasStates;

    public static function registerStates(): void
    {
        static::addState('state', StateConfig::make(BookingState::class)
            ->default(Draft::class)
            ->registerStates(BookingStateStatus::stateClasses())
            ->allowTransitionsFromArray(BookingStateStatus::transitions())
        );
    }
}

Benefits of the enum approach:

✅ 3 lines instead of 10+ for state configuration
✅ All transitions visible in one file (the enum)
✅ Easy to generate workflow diagrams
✅ Share workflows across multiple models

💡 See the demo: Booking.php

📚 Learn more: See Defining States and Transitions for all approaches.

Optional: Generate Enum & History Tracking

Generate enum from existing state classes:

php artisan stateflow:sync-enum App\\States\\Order\\OrderState
# Creates App\Enums\OrderStateStatus with all discovered states!

Naming Convention: By default, the command creates {BaseStateClass}Status (e.g., OrderState → OrderStateStatus). Use --enum=App\Enums\YourCustomName to specify a different name.

⚠️ Directory Requirement: The sync command only discovers state classes in the same directory as the base state class. If you add new states later, ensure they are in the correct directory (e.g., app/States/Order/ for OrderState).

Enable history tracking: Add ->recordHistory() to your StateConfig and use the HasStateHistory trait. See History Tracking.

How to use it

Basic Usage

$order = Order::create(['customer_name' => 'John Doe']);

// Check current state
$order->state;                              // Pending instance
$order->state->name();                      // 'pending'
$order->isInState('pending');               // true

// Check allowed transitions
$order->canTransitionTo('processing');      // true
$order->canTransitionTo('shipped');         // false (must process first)
$order->getNextStates();                    // [Processing::class, Cancelled::class]

// Transition
$result = $order->transitionTo('processing');
$result->succeeded();                       // true
$order->state->name();                      // 'processing'

💡 Full Example: See the laravel-stateflow-demo for a complete implementation — Order.php (model), OrderController.php (controller), and States/Order/ (state classes).

Serializing States

States are stored in the database using their NAME constant value:

// Creating with a state class
$order = Order::create([
    'state' => Processing::class,  // Stored as 'processing' in DB
]);

// The package handles serialization automatically
$order->state;              // Returns Processing instance
$order->state->name();      // 'processing'

Tip: You can use class names (e.g., Processing::class) throughout your code - the package handles mapping to/from database values.

Listing Registered States

// Get all states for the model (grouped by field)
Order::getStates();
// Returns: ['state' => ['pending', 'processing', 'shipped', 'delivered', 'cancelled']]

// Get states for a specific field
Order::getStatesFor('state');
// Returns: ['pending', 'processing', 'shipped', 'delivered', 'cancelled']

// Get default states
Order::getDefaultStates();
// Returns: ['state' => 'pending']

// Get default for specific field
Order::getDefaultStateFor('state');
// Returns: 'pending'

Retrieving Transitionable States

// Get state classes you can transition to from current state
$order->getNextStates();
// Returns: [Processing::class, Cancelled::class] (when in pending state)

// Count available transitions
count($order->getNextStates());
// Returns: 2

// Check if any transitions available
$order->hasNextStates();
// Returns: true

// Check specific transition
$order->canTransitionTo(Processing::class);
// Returns: true

Using States in Blade Templates

{{-- Display current state with color badge --}}
<span class="badge" style="background-color: {{ $order->state->color() }}">
    {{ $order->state->title() }}
</span>

{{-- Show available transition buttons --}}
@foreach($order->getNextStates() as $nextStateClass)
    <form action="{{ route('orders.transition', $order) }}" method="POST">
        @csrf
        <input type="hidden" name="state" value="{{ $nextStateClass::name() }}">
        <button type="submit" class="btn btn-{{ $nextStateClass::color() }}">
            <i class="{{ $nextStateClass::icon() }}"></i>
            {{ $nextStateClass::title() }}
        </button>
    </form>
@endforeach

Transitions

Basic Transition

$result = $order->transitionTo('processing');

if ($result->succeeded()) {
    // Transition completed
}

if ($result->failed()) {
    echo $result->error;  // Error message
}

With Metadata

$result = $order->transitionTo(
    state: Shipped::class,
    reason: 'Shipped via FedEx',
    metadata: ['tracking_number' => 'FX123456789']
);

Fluent API

$result = $order->transition()
    ->to(Shipped::class)
    ->reason('Order shipped')
    ->metadata(['carrier' => 'FedEx'])
    ->execute();

Silent Transition (No Events)

$order->transitionToWithoutEvents('processing');

Force Transition (Skip Validation)

$order->forceTransitionTo('delivered');

Permissions

StateFlow provides flexible permission control through role-based and policy-based authorization. Control who can perform state transitions based on user roles, ownership, or complex business logic.

📖 Complete Permissions Documentation

Quick example:

// Role-based: Define permitted roles in state class
#[StatePermission(roles: ['admin', 'warehouse'])]
class Shipped extends OrderState {}

// Policy-based: Complex authorization logic
class OrderPolicy {
    public function transitionToShipped(User $user, Order $order): bool {
        return $user->hasRole('warehouse') && $order->isPaid();
    }
}

// Check permissions
$order->userCanTransitionTo($user, 'shipped');

History Tracking

Enable History

use Hpwebdeveloper\LaravelStateflow\Concerns\HasStateHistory;

class Order extends Model implements HasStatesContract
{
    use HasStates, HasStateHistory;
}

Query History

// Get all history
$order->stateHistory;

// Get history for specific field
$order->stateHistoryFor('state');

// Get previous state
$order->previousState();

// Get initial state
$order->initialState();

History Record

$history = $order->stateHistory->first();

$history->from_state;    // 'pending'
$history->to_state;      // 'processing'
$history->reason;        // 'Order confirmed by warehouse'
$history->performer;     // User model
$history->metadata;      // ['key' => 'value']
$history->transitioned_at;

💡 See it in action: The demo shows complete history tracking with a timeline UI — see OrderController.php for how history is queried and formatted.

API Resources

State Resource

use Hpwebdeveloper\LaravelStateflow\Http\Resources\StateResource;

// Single state
return StateResource::make($order->state);

// All available states
return StateResource::collection($order->getAvailableStates());

// Response format
{
    "name": "pending",
    "title": "Pending",
    "color": "yellow",
    "icon": "clock",
    "description": "Order is pending confirmation",
    "is_current": true,
    "can_transition_to": true,
    "allowed_transitions": ["processing", "cancelled"]
}

In Controller

public function show(Order $order)
{
    return [
        'order' => $order,
        'current_state' => StateResource::make($order->state),
        'available_states' => StateResource::collection(
            $order->getAvailableStates()
        ),
    ];
}

Query Scopes

// By state
Order::whereState('shipped')->get();
Order::whereNotState('pending')->get();
Order::whereStateIn(['pending', 'processing'])->get();

// By transition capability
Order::whereCanTransitionTo('shipped')->get();

// History-based
Order::whereWasEverInState('processing')->get();
Order::whereNeverInState('cancelled')->get();

Validation Rules

use Hpwebdeveloper\LaravelStateflow\Validation\StateRule;
use Hpwebdeveloper\LaravelStateflow\Validation\TransitionRule;

// Validate state value
$request->validate([
    'state' => ['required', StateRule::make(OrderState::class)],
]);

// Validate transition is allowed
$request->validate([
    'new_state' => ['required', TransitionRule::make($order)],
]);

Events

use Hpwebdeveloper\LaravelStateflow\Events\StateTransitioning;
use Hpwebdeveloper\LaravelStateflow\Events\StateTransitioned;
use Hpwebdeveloper\LaravelStateflow\Events\TransitionFailed;

// In EventServiceProvider
protected $listen = [
    StateTransitioning::class => [
        ValidateInventory::class,
    ],
    StateTransitioned::class => [
        SendOrderNotification::class,
        UpdateInventory::class,
    ],
    TransitionFailed::class => [
        LogFailure::class,
    ],
];

Event Properties

// StateTransitioned event
$event->model;       // The model
$event->field;       // 'state'
$event->fromState;   // 'pending'
$event->toState;     // 'processing'
$event->performer;   // User who performed transition
$event->reason;      // Reason string
$event->metadata;    // Additional data

Artisan Commands

# Generate state class
php artisan make:state Pending --extends=OrderState

# Generate base state class
php artisan make:state OrderState --base

# Generate all states at once
php artisan make:state OrderState --states=Pending,Processing,Shipped,Delivered

# Generate enum from existing state classes
php artisan stateflow:sync-enum App\\States\\Order\\OrderState
# Or with custom enum name:
php artisan stateflow:sync-enum App\\States\\Order\\OrderState --enum=App\\Enums\\OrderWorkflow

# Generate transition class
php artisan make:transition ShipOrder

# List all states for a model
php artisan stateflow:list "App\Models\Order"

# Audit state configurations
php artisan stateflow:audit

🌟 Key Feature: The stateflow:sync-enum command scans your state directory and generates a workflow enum with all discovered states. This creates an enum with stateClasses(), canTransitionTo(), and transitions() methods ready for use in your model's registerStates() method.

Configuration Reference

// config/laravel-stateflow.php
return [
    // Default database column for state
    'default_state_field' => 'state',

    // Directory for generated state classes
    'states_directory' => 'States',

    // History tracking
    'history' => [
        'enabled' => true,
        'table' => 'state_histories',
        'prune_after_days' => null,
    ],

    // Permission system
    'permissions' => [
        'enabled' => true,
        'role_based' => true,
        'policy_based' => false,
        'throw_on_unauthorized' => true,
    ],

    // Event dispatching
    'events' => [
        'enabled' => true,
    ],
];

Common Patterns

Order Workflow

class Order extends Model implements HasStatesContract
{
    use HasStates;

    public static function registerStates(): void
    {
        static::addState('state', StateConfig::make(OrderState::class)
            ->default(Pending::class)
            ->allowTransition(Pending::class, Processing::class)
            ->allowTransition(Processing::class, Shipped::class)
            ->allowTransition(Shipped::class, Delivered::class)
            ->allowTransition(Pending::class, Cancelled::class)
            ->allowTransition(Processing::class, Cancelled::class)
        );
    }
}

💡 See this in action: The laravel-stateflow-demo demonstrates this workflow — see Order.php for the model and OrderController.php for the controller implementation.

Multiple State Fields

public static function registerStates(): void
{
    // Order status (main workflow)
    static::addState('state', StateConfig::make(OrderState::class)
        ->default(Pending::class)
        ->allowTransition(Pending::class, Processing::class)
        ->allowTransition(Processing::class, Shipped::class)
        ->allowTransition(Shipped::class, Delivered::class)
        ->allowTransition(Pending::class, Cancelled::class)
        ->allowTransition(Processing::class, Cancelled::class)
    );

    // Payment status (separate workflow)
    static::addState('payment_status', StateConfig::make(PaymentStatus::class)
        ->default(Unpaid::class)
        ->allowTransition(Unpaid::class, Paid::class)
        ->allowTransition(Paid::class, Refunded::class)
    );
}

// Usage
$order->transitionTo(Processing::class, field: 'state');
$order->transitionTo(Paid::class, field: 'payment_status');

Custom Transition Logic

php artisan make:transition ShipOrder

// app/Transitions/ShipOrder.php
use Hpwebdeveloper\LaravelStateflow\Transition;

class ShipOrder extends Transition
{
    public function handle(): void
    {
        $this->model->shipped_at = now();
        $this->model->save();

        // Send notification, update inventory, etc.
    }

    public function canTransition(): bool
    {
        return $this->model->shipping_address !== null
            && $this->model->total > 0;
    }
}

Register in config:

->allowTransition(Processing::class, Shipped::class, ShipOrder::class)

Dependency Injection in Transitions

The handle() method supports dependency injection via Laravel's container:

use App\Services\NotificationService;
use App\Services\InventoryService;

class ShipOrder extends Transition
{
    public function handle(
        NotificationService $notifications,
        InventoryService $inventory
    ): void {
        $this->model->shipped_at = now();
        $this->model->save();

        // Services are automatically resolved from the container
        $notifications->sendShippedNotification($this->model);
        $inventory->decrementStock($this->model->items);
    }
}

This allows for clean separation of concerns and easier testing through dependency mocking.

Version Compatibility

Package Version	Laravel Versions	PHP Versions	Status
1.x	12.x	8.3+	Active support

Note: The package is currently built for Laravel 12 with PHP 8.3+. Support for earlier Laravel versions may be added in future releases.

Credits

Hamed Panjeh
All Contributors
Icon in the above image: Flow Chart by Bernd Lakenbrink from Noun Project (CC BY 3.0)

License

The MIT License (MIT). See License File for more information.

Name		Name	Last commit message	Last commit date
Latest commit History 5 Commits
.githooks		.githooks
.github		.github
config		config
database/migrations		database/migrations
docs		docs
src		src
stubs		stubs
tests		tests
.gitattributes		.gitattributes
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
LICENSE.md		LICENSE.md
README.md		README.md
composer.json		composer.json
phpstan-local.neon		phpstan-local.neon
phpstan.neon		phpstan.neon
phpstan.neon.dist		phpstan.neon.dist
phpunit.xml.dist		phpunit.xml.dist
pint.json		pint.json

License

HPWebdeveloper/laravel-stateflow

Folders and files

Latest commit

History

Repository files navigation

Laravel StateFlow

📚 Table of Contents

Introduction

Why Laravel StateFlow?

The Problem: Manual State Management in Legacy Systems

🤦‍♂️ This creates several pain points:

Laravel-StateFlow's Solution: Centralized State Topology

⭐️⭐️⭐️⭐️⭐️ Key Innovations

Installation

Preparation in 4 simple Steps

1. Add State Column to Your Model

2. Create State Classes

3. Configure States

3.1 Traditional Approach — State Classes with Metadata

3.2 Hybrid Enum Approach — Centralized Workflow Topology

4. Add to Model

4.1 Traditional Approach — Explicit Transitions

4.2 Hybrid Enum Approach — Clean & Elegant ✨

Optional: Generate Enum & History Tracking

How to use it

Basic Usage

Serializing States

Listing Registered States

Retrieving Transitionable States

Using States in Blade Templates

Transitions

Basic Transition

With Metadata

Fluent API

Silent Transition (No Events)

Force Transition (Skip Validation)

Permissions

History Tracking

Enable History

Query History

History Record

API Resources

State Resource

In Controller

Query Scopes

Validation Rules

Events

Event Properties

Artisan Commands

Configuration Reference

Common Patterns

Order Workflow

Multiple State Fields

Custom Transition Logic

Dependency Injection in Transitions

Version Compatibility

Credits

License

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 1

Packages 0

Languages

Packages