Download the PHP package solution-forest/workflow-state-machine without Composer

Laravel Workflow State Machine

A powerful and flexible Laravel workflow state machine library that makes it easy to manage model state transitions, rule validation, and audit tracking.

Features

🎯 Core Features

• Configurable Status Management: Customize status lists in config files
• Polymorphic Relations Support: Add workflow support to any model via Traits
• Permission Control: Control which users can change specific model statuses
• Rule Engine: Define and assign multiple rules to processes
• Automated Workflows: Set whether status changes automatically after rules pass
• Event-Driven Auto Transition: Uses Laravel's event system to trigger automatic transitions
• Workflow Roadmaps: Group multiple processes into workflows with status roadmaps
• Audit Logging: Complete tracking of all status change records
• Rollback Support: Support for status rollback operations

🔧 Technical Features

• High Test Coverage: Using Pest testing framework
• Code Quality: Formatted with Pint and Larastan (Laravel-optimized PHPStan) Level 5 static analysis
• Modular Design: Flexible Trait system
• Database Optimized: Efficient polymorphic relationship design
• Laravel Events Integration: Automatic transition triggers on model updates

Quick Start

Installation

Publish Configuration

This will publish the configuration file to config/workflow-state-machine.php where you can customize statuses and other settings.

Run Migrations

Basic Usage

1. Setup Manageable Models

Add the HasWorkflowStates trait to your models:

2. Setup Permission Control

Add the CanManageWorkflowStates trait to user models that can change statuses:

3. Configure Status Lists

Customize statuses in config/workflow-state-machine.php:

Custom Status Column Name

By default, the library expects your models to have a status column. You can customize this in two ways:

1. Model-level customization (recommended)

Define a $status_column property in your model:

2. Global configuration

Set the default status column name in config/workflow-state-machine.php:

Note: Model-level $status_column property takes precedence over the global config setting.

Status Attribute Accessor

The HasWorkflowStates trait provides a dynamic status attribute accessor that automatically uses your configured status column. This means you can always access the status via $model->status, regardless of the actual database column name:

This accessor provides a consistent interface while allowing flexible database schema design.

Custom Status Array

You can also define custom status arrays at the model level, allowing different models to have different workflow statuses:

Model-level status array (recommended for model-specific workflows)

Define a $status_array property in your model:

Benefits of model-level status arrays:

1. Different workflows for different models: Orders can have different statuses than Tasks
2. Auto-workflow creation: Uses model-specific statuses for starting/ending status
3. Auto-process generation: Creates processes based on model's status array
4. Flexible configuration: Each model can define its own workflow logic

Fallback behavior:

• Model status array → Global config status array → Hardcoded default

4. Create Workflows and Processes

WorkflowProcess Properties

Each WorkflowProcess has the following properties:

• workflow_id: The ID of the workflow this process belongs to
• name: A descriptive name for the process (optional)
• from_status: The status this process transitions from
• to_status: The status this process transitions to
• order: The order of this process in the workflow sequence
• auto_transition: Whether this process should automatically transition when triggered
• completed: Whether this process has been completed (useful for tracking progress)
• description: A detailed description of what this process does (optional)

Auto-Create Processes Feature

When auto_create_processes is enabled in the configuration, the library will automatically create workflow processes based on the status array when a workflow is created:

Auto-Create Workflow Feature

This feature allows workflows to be automatically created when models with the HasWorkflowStates trait are created.

Configuration

Enable auto-creation in your config file:

Usage

Once enabled, any model that uses the HasWorkflowStates trait will automatically get a workflow created when the model is saved for the first time:

Auto-Creation Features

1. Automatic Workflow Creation: When a model is created, a workflow is automatically generated if:

   • The model uses the HasWorkflowStates trait
   • auto_create_workflow is enabled in config
   • The model doesn't already have a workflow

2. Process Auto-Generation: If auto_create_processes is enabled, the workflow will automatically create processes based on the status configuration via the WorkflowCreated event:

3. Initial Status Assignment: If the model doesn't have a status when created, it will be automatically set to the first status in the configuration (typically 'draft').

4. No Duplicate Creation: The system checks if a model already has a workflow and won't create duplicates.

Observer Events

The auto-creation is handled by the WorkflowModelObserver which listens for Eloquent created events. This ensures workflows are created immediately when models are saved to the database.

Manual Control

You can also manually create workflows using the service:

Best Practices

1. Enable selectively: Only enable auto-creation for models that truly need workflows
2. Configure statuses: Ensure your status configuration matches your business needs
3. Testing: Always test auto-creation in your test environment first

Disabling Auto-Creation

To disable auto-creation for specific models while keeping it enabled globally, you can override the observer behavior or check model-specific conditions in your implementation.

Configuration Options

5. Define Rules and Sample Rule Class

Creating Rules with Artisan Command

The quickest way to create workflow rules is using the workflow:make-rule command:

Command Options:

• name (required): The name of the rule class
• --description: Description of the rule (optional)
• --active: Whether the rule is active by default (default: true)
• --no-database: Skip inserting the rule into the database

The command generates a rule class in app/Rules/ that implements the WorkflowRuleContract:

Manual Rule Creation

Create custom rule classes that implement the rule interface:

Example Rule Implementations

User Permission Rule:

Model State Rule:

Time-based Rule:

Attaching Rules to Processes

php use WorkflowStateMachine\Models\WorkflowProcess; use WorkflowStateMachine\Models\WorkflowRule;

// Create rule (or use the one created by the artisan command) $rule = WorkflowRule::create([ 'name' => 'check_user_permission', 'description' => 'Check if user has permission to change status', 'rule_class' => 'App\Rules\UserPermissionRule', ]);

// Or find an existing rule created by the command $rule = WorkflowRule::where('rule_class', 'App\Rules\CustomRule')->first();

// Assign rule to process $process = WorkflowProcess::find(1); $process->rules()->attach($rule); bash

Run tests

composer test

Run code formatting

composer pint

Run static analysis with Larastan

composer larastan

Or run PHPStan directly

composer phpstan

Run PHPStan manually with memory limit

vendor/bin/phpstan analyse --memory-limit=256M

## Requirements

- PHP ^8.2
- Laravel ^11.0

## Versioning

This project follows [Semantic Versioning](https://semver.org/). Versions are tagged and released through GitHub.

For version history, see [CHANGELOG.md](CHANGELOG.md).

## Contributing

Pull requests and issues are welcome! See [VERSION_RELEASE.md](VERSION_RELEASE.md) for release procedures.

## License

MIT License. See [LICENSE](LICENSE) file for details.

## Support

For questions or suggestions:

1. Check the [documentation](docs/)
2. Search [existing issues](https://github.com/solution-forest/workflow-state-machine/issues)
3. Create a new [Issue](https://github.com/solution-forest/workflow-state-machine/issues/new)

---

**Make workflow management simple and powerful!** 🚀