README

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

📖 Table of Contents

• Overview
• ✨ Features
• 📦 Installation
• 🚀 Quick Start
• 📚 Complete Documentation
• 💡 Examples & Use Cases
• 🔧 Requirements
• 🧪 Testing
• 🚀 Performance
• 🤝 Contributing
• 🔒 Security
• 📄 License

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

• 📄 YAML Configuration - Complete YAML syntax and options
• 🛡️ Guards & Actions - Pre/post transition logic
• 🎯 Events System - State change events and listeners
• 📊 State History - Track and audit state changes

🔧 Advanced Topics

• ⚙️ Configuration Guide - Package configuration options
• 🎨 Console Commands - Artisan commands reference
• 🧪 Testing Guide - Testing your state machines

📖 Getting Started

• 🏠 Wiki Home - Complete documentation homepage
• 📦 Installation & Setup - Detailed installation guide
• 🚀 Basic Usage Guide - Step-by-step tutorial

💡 Examples & Use Cases

Explore real-world implementations and patterns:

• 📚 Examples Collection - Complete examples overview
• 📦 Order Workflow Example - E-commerce order processing
• 📰 Article Publishing Example - Content management workflow
• 💳 User Subscription Example - Subscription lifecycle management
• 🎯 Event Usage Example - Advanced event handling

🔧 Requirements

• PHP 8.2 or higher
• Laravel 11.x or higher
• 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.

📄 License

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

Made with ❤️ for the Laravel community

Resources

• 📖 Documentation
• 💬 Discussions
• 🐛 Issue Tracker
• 📦 Packagist

Community Links

• CODE_OF_CONDUCT.md - Our code of conduct
• CONTRIBUTING.md - How to contribute
• SECURITY.md - Security policy
• RELEASES.md - Release notes and changelog