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

Installation
Quick Start
Documentation
Examples
Testing
Contributing
License

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"

Quick Start

1. Create a Workflow-Enabled Model

<?php

namespace App\Models;

use CleaniqueCoders\Flowstone\Concerns\InteractsWithWorkflow;
use CleaniqueCoders\Flowstone\Contracts\Workflow as WorkflowContract;
use CleaniqueCoders\Flowstone\Enums\Status;
use Illuminate\Database\Eloquent\Casts\Attribute;
use Illuminate\Database\Eloquent\Model;

class Document extends Model implements WorkflowContract
{
    use InteractsWithWorkflow;

    protected $fillable = ['title', 'content', 'status', 'author_id'];

    public function workflowType(): Attribute
    {
        return Attribute::make(get: fn () => 'document-approval');
    }

    public function workflowTypeField(): Attribute
    {
        return Attribute::make(get: fn () => 'workflow_type');
    }

    public function getMarking(): string
    {
        return $this->status ?? Status::DRAFT->value;
    }

    public function setMarking(string $marking): void
    {
        $this->status = $marking;
    }
}

2. Configure Your Workflow

Create a workflow configuration in the database:

use CleaniqueCoders\Flowstone\Models\Workflow;
use CleaniqueCoders\Flowstone\Models\WorkflowPlace;
use CleaniqueCoders\Flowstone\Models\WorkflowTransition;

// Create workflow
$workflow = Workflow::create([
    'name' => 'document-approval',
    'type' => 'state_machine',
    'initial_marking' => 'draft',
]);

// Add places (states)
foreach (['draft', 'review', 'approved', 'rejected'] as $place) {
    WorkflowPlace::create([
        'workflow_id' => $workflow->id,
        'name' => $place,
    ]);
}

// Add transitions
WorkflowTransition::create([
    'workflow_id' => $workflow->id,
    'name' => 'submit',
    'from_place' => 'draft',
    'to_place' => 'review',
]);

3. Use the Workflow

// Create a document
$document = Document::create([
    'title' => 'My Document',
    'content' => 'Document content...',
    'status' => 'draft',
]);

// Get available transitions
$transitions = $document->getEnabledToTransitions();
// Returns: ['review' => 'Review']

// Apply a transition
$workflow = $document->getWorkflow();
if ($workflow->can($document, 'submit')) {
    $workflow->apply($document, 'submit');
    $document->save(); // Now status is 'review'
}

Documentation

Comprehensive documentation is available in the docs/ directory:

Installation Guide - Detailed setup instructions
Configuration Reference - Complete configuration options
Quick Start Guide - Get up and running quickly
Usage Guide - Detailed usage instructions
API Reference - Complete API documentation
Database Workflows - Database-driven configurations
Advanced Usage - Complex scenarios and patterns

Examples

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

Document Approval - Classic approval process with roles
E-commerce Orders - Order lifecycle management
Content Publishing - Editorial workflow with scheduling
Bug Tracking - Issue management for development teams
Employee Onboarding - HR workflow with multi-department coordination

Each example includes complete implementation with models, controllers, views, and tests.

Testing

composer test

Contributing

Please see CONTRIBUTING for details.

License

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

cleaniquecoders / flowstone

Maintainers

Details