README

Flowstone is a powerful Laravel package that integrates the robust Symfony Workflow engine into your Laravel applications. Build sophisticated workflow and state machine systems with database-driven configurations, role-based permissions, and seamless Laravel integration.

🚀 Key Features

• 🔄 Database-Driven Workflows - Configure workflows through the database for runtime flexibility
• 🏛️ Symfony Workflow Integration - Built on the proven Symfony Workflow component
• 👥 Role-Based Permissions - Control who can perform transitions with metadata-driven roles
• 📊 Predefined Status Enum - Ready-to-use workflow states (Draft, Pending, Approved, etc.)
• ⚡ Performance Optimized - Workflow configuration caching and efficient queries
• 🎯 Multiple Workflow Types - Support for both State Machines and Workflows

💡 Why Flowstone?

Laravel-Native Workflow Integration

Unlike Symfony's configuration-based approach, Flowstone uses Laravel traits for better developer experience:

// ✅ Flowstone way - Full IDE support!
class Document extends Model implements WorkflowContract
{
    use InteractsWithWorkflow;  // Get 50+ workflow methods instantly

    // IDE autocomplete ✅ | Type hints ✅ | Dynamic workflows ✅
}

// ❌ Symfony way - Config-based, no IDE support
'supports' => [App\Models\Document::class],  // Hard-coded in config

Benefits:

• ✅ Full IDE Autocomplete - IntelliSense for all workflow methods
• ✅ Type Safety - Compile-time type checking
• ✅ Dynamic Workflows - Choose workflows at runtime
• ✅ Self-Documenting - Just look at the model to see workflow support
• ✅ Better Testing - Mock workflow behavior directly

See detailed comparison in docs.

Table of Contents

• Requirements
• Installation
• Documentation
• Examples
• Testing
• Contributing
• License

Requirements

• PHP: 8.2, 8.3, or 8.4
• Laravel: 10.x, 11.x, or 12.x
• Database: MySQL, PostgreSQL, SQLite, or SQL Server

Version Compatibility

Note: Laravel 9 is not supported due to dependency requirements. Laravel 9 reached end-of-life in February 2024.

Installation

Install Flowstone via Composer:

composer require cleaniquecoders/flowstone

Publish and run the migrations:

php artisan vendor:publish --tag="flowstone-migrations"
php artisan migrate

Optionally, publish the configuration file:

php artisan vendor:publish --tag="flowstone-config"

Documentation

Comprehensive documentation is available in the docs/ directory:

• Getting Started - Installation and quick start guide
• Configuration - Configure workflows, UI, and performance
• Usage Guide - Workflows, details, and visual designer
• API Reference - Complete API documentation

Examples

Real-world examples are available in the examples/ directory:

• Bug Tracking - Issue lifecycle management
• Content Publishing - Content approval workflow
• Document Approval - Multi-step approval process
• E-commerce Order - Order fulfillment workflow
• Employee Onboarding - New hire process

Testing

composer test

Contributing

Please see CONTRIBUTING for details.

License

The MIT License (MIT). Please see License File for more information.