Saltar al contenido
Jefferson Gonçalves
← Volver a proyectos

Laravel Statecraft

A declarative and testable way to model entity state transitions (orders, documents, processes…) with guard conditions, actions, and events.

#Laravel Statecraft

Laravel Statecraft

[!TIP] What Laravel Statecraft does for you — Describe order, approval or onboarding workflows as state machines in YAML — states, transitions, guards and actions — instead of scattering if ($status === ...) checks across your codebase.

This package is free and maintained on my own time. If it saves you hours, a small contribution helps me keep it going: 💖 GitHub Sponsors · ☕ Buy Me a Coffee · PayPal

Advanced State Machine implementation for Laravel applications. Declarative state management with support for conditions, actions, and complex workflows through YAML configuration.

Latest Version Total Downloads License PHP Version Laravel Version Tests Code Style

#📖 Table of Contents

#Overview

Laravel Statecraft is a powerful state machine implementation for Laravel that provides declarative state management through YAML configuration. Build complex workflows with conditional transitions, guards, actions, and comprehensive state tracking.

Perfect for order processing, user workflows, approval systems, and any application requiring sophisticated state management.

#🎯 Use Cases

Laravel Statecraft is perfect for:

  • Order Processing - Complex e-commerce order workflows
  • User Registration - Multi-step user onboarding flows
  • Approval Systems - Document or request approval workflows
  • Content Management - Publishing and moderation workflows
  • Business Processes - Any multi-state business logic

#✨ Features

  • 🚀 Declarative Configuration - Define state machines in YAML files
  • 🔄 Flexible Transitions - Conditional transitions with guards and actions
  • 🎯 Event System - Built-in events for state changes and transitions
  • 📊 State History - Track all state changes with timestamps
  • 🛡️ Guards & Actions - Pre/post transition validation and processing
  • 🔗 Model Integration - Seamless Eloquent model integration
  • 📋 YAML Support - Human-readable state machine definitions
  • 🎨 Artisan Commands - CLI tools for state machine management
  • ✅ Validation - Comprehensive state machine validation
  • 📈 Visualization - Export state machines to Mermaid diagrams
  • 🧪 Test-Friendly - Built-in testing utilities
  • ⚡ Performance - Optimized for speed with caching support

#📦 Installation

Detailed installation instructions are available in our wiki: 📦 Installation & Setup

Quick install via Composer:

composer require grazulex/laravel-statecraft

💡 Auto-Discovery
The service provider will be automatically registered thanks to Laravel's package auto-discovery.

Publish configuration:

php artisan vendor:publish --tag=statecraft-config

Publish migrations (if using history tracking):

php artisan vendor:publish --tag=statecraft-migrations
php artisan migrate

#🚀 Quick Start

For a complete getting started guide, visit: 🚀 Basic Usage Guide

#1. Create a State Machine Definition

php artisan statecraft:make OrderStateMachine --model=Order

#2. Define Your State Machine in YAML

# state-machines/OrderStateMachine.yaml
name: OrderStateMachine
model: App\Models\Order
initial_state: pending

states:
  - name: pending
    description: Order is pending payment
  - name: paid
    description: Order has been paid
  - name: shipped
    description: Order has been shipped

transitions:
  - name: pay
    from: pending
    to: paid
    guard: PaymentGuard
    action: ProcessPayment

#3. Add the Trait to Your Model

use Grazulex\LaravelStatecraft\HasStateMachine;

class Order extends Model
{
    use HasStateMachine;
    
    protected $stateMachine = 'OrderStateMachine';
}

#4. Use State Transitions

// Create a new order (starts in 'pending' state)
$order = Order::create(['total' => 100.00]);

// Transition to next state
$order->transition('pay'); // Moves to 'paid' state

// Check current state
echo $order->currentState(); // 'paid'

#📚 Complete Documentation

Our comprehensive documentation is available in the GitHub Wiki:

#🏗️ Core Concepts

#🔧 Advanced Topics

#📖 Getting Started

#💡 Examples & Use Cases

Explore real-world implementations and patterns:

#🔧 Requirements

  • PHP 8.3 or higher
  • Laravel 12.x or 13.x
  • Optional: Redis for caching (recommended for production)

#🧪 Testing

Comprehensive testing guide: 🧪 Testing Guide

composer test
composer test:coverage
composer test:types

#🚀 Performance

Laravel Statecraft is optimized for production use with caching support and minimal overhead. See our ⚙️ Configuration Guide for performance optimization tips.

#🤝 Contributing

We welcome contributions! Please see CONTRIBUTING.md for details.

Before contributing:

  1. Read our Code of Conduct
  2. Check the issue tracker
  3. Review our 📚 Complete Documentation

#🔒 Security

If you discover a security vulnerability, please send an e-mail via the security policy. All security vulnerabilities will be promptly addressed.

#💖 Support This Package

Laravel Statecraft is free, open source and maintained on my own time. If it saves you hours, here is how you can give back:

#📄 License

Laravel Statecraft is open-sourced software licensed under the MIT license.

Made with ❤️ for the Laravel community

#Resources

#Community Links

Nueva versión disponible.