Download the PHP package hpwebdeveloper/laravel-stateflow without Composer

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?
  • The Problem with Manual Transitions
  • StateFlow's Solution
  • Key Innovations
• 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.

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:

🤦‍♂️ 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:

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:

💡 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:

Installation

Publish the config (optional):

For history tracking, publish and run migrations:

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:

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:

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

Alternative: You can also create states individually:

💡 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:

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()).

💡 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).

The Enum — Shows all transitions in one place:

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

💡 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

💡 See the demo: Order.php

4.2 Hybrid Enum Approach — Clean & Elegant ✨

With the enum approach, your model becomes remarkably clean:

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:

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

💡 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:

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

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

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:

History Tracking

Enable History

Query History

History Record

💡 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

In Controller

Query Scopes

Validation Rules

Events

Event Properties

Artisan Commands

🌟 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

Common Patterns

Order Workflow

💡 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

Custom Transition Logic

Register in config:

Dependency Injection in Transitions

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

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

Version Compatibility

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.