Home

🎯 Laravel Statecraft

Advanced State Machine implementation for Laravel applications

Laravel Statecraft 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.

🌟 Why Laravel Statecraft?

• 📄 YAML-Driven: Define state machines in simple, readable 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
• 🎨 CLI Tools: Artisan commands for state machine management
• 📈 Visualization: Export state machines to Mermaid diagrams
• 🧪 Test-Friendly: Built-in testing utilities

⚡ Quick Start

1. Install the Package

composer require grazulex/laravel-statecraft

2. Create Your First State Machine

php artisan statecraft:make OrderStateMachine --model=Order

3. Define States and Transitions 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
  
  - name: ship
    from: paid
    to: shipped
    action: CreateShipment

4. Add the Trait to Your Model

use Grazulex\LaravelStatecraft\HasStateMachine;

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

5. Use State Transitions

$order = Order::create(['amount' => 100]);

// Check current state
$order->getCurrentState(); // 'pending'

// Transition to next state
$order->transitionTo('pay');
$order->getCurrentState(); // 'paid'

// Check if transition is possible
$order->canTransitionTo('ship'); // true

🎯 Use Cases

Laravel Statecraft excels in scenarios requiring complex state management:

• 📦 Order Processing - E-commerce order workflows with payment, fulfillment, and shipping
• 👥 User Registration - Multi-step user onboarding and verification processes
• 📝 Approval Systems - Document review, request approval, and content moderation
• 📰 Content Publishing - Article drafting, review, and publication workflows
• 💳 Subscription Management - User subscription lifecycle and payment handling

📚 Documentation

Ready to dive deeper? Our comprehensive guides will get you up to speed:

Getting Started

• Installation & Setup - Install and configure Laravel Statecraft
• Basic Usage Guide - Learn the fundamentals
• Your First State Machine - Step-by-step tutorial

Core Concepts

• YAML Configuration - Complete YAML syntax reference
• Guards & Actions - Implement conditional logic and side effects
• Events System - Handle state change events
• State History - Track and audit state changes

Advanced Topics

• Console Commands - CLI tools and utilities
• Testing Guide - Test your state machines effectively

Examples

• Order Workflow Example - Complete e-commerce order processing
• Article Publishing Example - Content management workflow
• User Subscription Example - Subscription lifecycle management
• Event Usage Example - Working with state machine events
• Examples Collection - More real-world examples

🚀 What's Next?

1. Install Laravel Statecraft and get up and running in minutes
2. Follow the Basic Usage Guide to understand core concepts
3. Explore Examples to see real-world implementations
4. Join our Community and contribute to the project

---

Ready to transform your Laravel application's state management? Let's get started! 🎯