README

A powerful, framework-agnostic workflow engine for PHP applications. This core library provides comprehensive workflow definition, execution, and state management capabilities without any framework dependencies.

⚠️ WARNING: DEVELOPMENT STATUS⚠️

This package is currently under active development and is NOT READY FOR PRODUCTION USE.

Features may be incomplete, APIs might change, and there could be breaking changes. Use at your own risk in development environments only.

📋 Requirements

PHP 8.3+ - Leverages modern PHP features for type safety and performance
Composer - For dependency management
No framework dependencies - Works with any PHP project

✨ Features

🚀 Framework Agnostic: Works with any PHP framework or standalone applications
🔒 Type Safe: Full PHP 8.3+ type safety with strict typing and generics
🔧 Extensible: Plugin architecture for custom actions and storage adapters
📊 State Management: Robust workflow instance state tracking and persistence
⚡ Performance: Optimized for high-throughput workflow execution
🛡️ Error Handling: Comprehensive exception handling with detailed context
🔄 Retry Logic: Built-in retry mechanisms with configurable strategies
⏱️ Timeouts: Step-level timeout controls for reliable execution
📋 Conditions: Conditional workflow execution based on runtime data
🎯 Events: Rich event system for monitoring and integration
🧪 Well Tested: Comprehensive test suite with 160+ assertions

📦 Installation

For Production Use

composer require solution-forest/workflow-engine-core

For Development

# Clone the repository
git clone https://github.com/solution-forest/workflow-engine-core.git
cd workflow-engine-core

# Install dependencies
composer install

# Run quality checks
composer ci

🚀 Quick Start

Basic Workflow Definition

use SolutionForest\WorkflowEngine\Core\WorkflowBuilder;
use SolutionForest\WorkflowEngine\Core\WorkflowEngine;
use SolutionForest\WorkflowEngine\Core\WorkflowContext;
use SolutionForest\WorkflowEngine\Actions\BaseAction;

// Define custom actions
class ValidateOrderAction extends BaseAction
{
    public function execute(WorkflowContext $context): ActionResult
    {
        $orderId = $context->getData('order_id');
        
        // Your validation logic here
        if ($this->isValidOrder($orderId)) {
            return ActionResult::success(['validated' => true]);
        }
        
        return ActionResult::failure('Invalid order');
    }
}

// Create a workflow
$workflow = WorkflowBuilder::create('order-processing')
    ->addStep('validate', ValidateOrderAction::class)
    ->addStep('payment', ProcessPaymentAction::class)
    ->addStep('fulfillment', FulfillOrderAction::class)
    ->addTransition('validate', 'payment')
    ->addTransition('payment', 'fulfillment')
    ->build();

// Execute the workflow
$engine = new WorkflowEngine();
$context = new WorkflowContext(
    workflowId: 'order-processing',
    stepId: 'validate',
    data: ['order_id' => 123, 'customer_id' => 456]
);

$instance = $engine->start($workflow, $context);
$result = $engine->executeStep($instance, $context);

Advanced Features

Conditional Steps

use SolutionForest\WorkflowEngine\Attributes\Condition;

class ConditionalAction extends BaseAction
{
    #[Condition("data.amount > 1000")]
    public function execute(WorkflowContext $context): ActionResult
    {
        // This action only executes if amount > 1000
        return ActionResult::success();
    }
}

Retry Logic

use SolutionForest\WorkflowEngine\Attributes\Retry;

class ReliableAction extends BaseAction
{
    #[Retry(maxAttempts: 3, delay: 1000)]
    public function execute(WorkflowContext $context): ActionResult
    {
        // This action will retry up to 3 times with 1 second delay
        return ActionResult::success();
    }
}

Timeouts

use SolutionForest\WorkflowEngine\Attributes\Timeout;

class TimedAction extends BaseAction
{
    #[Timeout(seconds: 30)]
    public function execute(WorkflowContext $context): ActionResult
    {
        // This action will timeout after 30 seconds
        return ActionResult::success();
    }
}

🏗️ Architecture

The workflow engine follows a clean architecture pattern with clear separation of concerns:

┌─────────────────┐
│   Workflow      │
│   Builder       │
└─────────────────┘
         │
         ▼
┌─────────────────┐    ┌─────────────────┐
│   Workflow      │◄───│   Workflow      │
│   Definition    │    │   Engine        │
└─────────────────┘    └─────────────────┘
         │                       │
         ▼                       ▼
┌─────────────────┐    ┌─────────────────┐
│     Steps       │    │    Executor     │
│   & Actions     │    │                 │
└─────────────────┘    └─────────────────┘
         │                       │
         ▼                       ▼
┌─────────────────┐    ┌─────────────────┐
│     State       │    │     Events      │
│   Manager       │    │   Dispatcher    │
└─────────────────┘    └─────────────────┘

📝 Workflow Builder

Purpose: Fluent interface for creating workflow definitions
Responsibilities:
- Provides method chaining (.addStep(), .when(), .email(), etc.)
- Validates workflow structure during construction
- Creates immutable workflow definitions
- Supports conditional steps and common patterns
Example: WorkflowBuilder::create('user-onboarding')->addStep(...)->build()

📋 Workflow Definition

Purpose: Immutable data structure representing a complete workflow
Responsibilities:
- Contains workflow metadata (name, description, version)
- Stores all steps and their relationships
- Defines step execution order and conditions
- Serves as a blueprint for workflow execution
Key data: Steps, transitions, conditions, metadata

⚡ Workflow Engine

Purpose: Central orchestrator that manages workflow execution
Responsibilities:
- Starts new workflow instances from definitions
- Manages workflow lifecycle (start, pause, resume, cancel)
- Coordinates between different components
- Provides API for workflow operations
Main methods: start(), pause(), resume(), cancel(), getInstance()

🎯 Steps & Actions

Purpose: Individual workflow tasks and their implementations
Responsibilities:
- Steps: Define what should happen (metadata, config, conditions)
- Actions: Implement the actual business logic (execute() method)
- Handle step-specific configuration (timeout, retry, conditions)
- Support compensation actions for rollback scenarios
Examples: SendEmailAction, CreateUserAction, ValidateOrderAction

🎬 Executor

Purpose: Runtime engine that executes individual workflow steps
Responsibilities:
- Executes actions in the correct sequence
- Handles conditional execution based on workflow context
- Manages timeouts and retry logic
- Processes step transitions and flow control
- Handles errors and compensation

🗄️ State Manager

Purpose: Component responsible for workflow instance state persistence
Responsibilities:
- Saves/loads workflow instances to/from storage
- Tracks workflow execution state (running, paused, completed, failed)
- Manages workflow context data
- Handles state transitions and validation
- Supports different storage adapters (database, file, memory)

📡 Events Dispatcher

Purpose: Event system for monitoring and integration
Responsibilities:
- Fires events during workflow execution
- Enables workflow monitoring and logging
- Supports custom event listeners
- Provides hooks for external system integration
- Events: WorkflowStarted, StepCompleted, WorkflowFailed, etc.

🔄 Data Flow

Builder → creates → Definition
Engine → uses Definition to create instances
Engine → delegates to Executor for step execution
Executor → runs → Steps & Actions
State Manager → persists → workflow state
Events Dispatcher → broadcasts → execution events

✅ Architecture Benefits

Separation of concerns - each component has a single responsibility
Extensibility - you can swap out storage adapters, add custom actions
Testability - each component can be tested independently
Framework agnostic - no dependencies on specific frameworks
Type safety - full PHP 8.3+ type hints throughout

🔧 Configuration

Storage Adapters

Implement the StorageAdapter interface for custom storage:

use SolutionForest\WorkflowEngine\Contracts\StorageAdapter;

class CustomStorageAdapter implements StorageAdapter
{
    public function save(WorkflowInstance $instance): void
    {
        // Save workflow instance to your storage
    }

    public function load(string $instanceId): ?WorkflowInstance
    {
        // Load workflow instance from your storage
    }

    public function delete(string $instanceId): void
    {
        // Delete workflow instance from your storage
    }
}

Event Handling

Listen to workflow events:

use SolutionForest\WorkflowEngine\Contracts\EventDispatcher;

class CustomEventDispatcher implements EventDispatcher
{
    public function dispatch(object $event): void
    {
        // Handle workflow events
        match (get_class($event)) {
            'SolutionForest\WorkflowEngine\Events\WorkflowStarted' => $this->onWorkflowStarted($event),
            'SolutionForest\WorkflowEngine\Events\StepCompletedEvent' => $this->onStepCompleted($event),
            'SolutionForest\WorkflowEngine\Events\WorkflowCompletedEvent' => $this->onWorkflowCompleted($event),
            default => null,
        };
    }
}

Logging

Provide custom logging implementation:

use SolutionForest\WorkflowEngine\Contracts\Logger;

class CustomLogger implements Logger
{
    public function info(string $message, array $context = []): void
    {
        // Log info messages
    }

    public function error(string $message, array $context = []): void
    {
        // Log error messages
    }

    public function warning(string $message, array $context = []): void
    {
        // Log warning messages
    }
}

🧪 Development

Testing

Run the test suite:

# Run all tests
composer test

# Run tests with coverage
composer test:coverage

# Run specific test file
vendor/bin/pest tests/Unit/WorkflowEngineTest.php

# Run tests with detailed output
vendor/bin/pest --verbose

Code Quality

We use several tools to maintain high code quality:

# Static analysis with PHPStan
composer analyze

# Code formatting with Laravel Pint
composer pint

# Check code formatting without making changes
composer pint --test

# Run all quality checks
composer pint && composer analyze && composer test

Development Tools

Pest - Testing framework with expressive syntax
Pest Architecture Testing - Architectural constraints and code quality rules
PHPStan - Static analysis tool for catching bugs
Laravel Pint - Code style fixer built on PHP-CS-Fixer
Framework-agnostic - No Laravel dependencies in the core library

Configuration Files

phpstan.neon.dist - PHPStan configuration for static analysis
pint.json - Laravel Pint configuration for code formatting
phpunit.xml.dist - PHPUnit configuration for testing
.github/workflows/run-tests.yml - CI/CD pipeline configuration

Quality Standards

We maintain high code quality through:

100% PHPStan Level 6 - Static analysis with no errors
Laravel Pint - Consistent code formatting following Laravel standards
Comprehensive Testing - 40 tests with 160+ assertions covering all core functionality
Type Safety - Full PHP 8.3+ type declarations and documentation
Continuous Integration - Automated quality checks on every commit

📚 Framework Integrations

This core library is framework-agnostic. For specific framework integrations:

Laravel: Use solution-forest/workflow-engine-laravel
Symfony: Coming soon
Other frameworks: Easily integrate using the provided interfaces

🤝 Contributing

We welcome contributions! Please see CONTRIBUTING.md for details.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Credits

Solution Forest Team - Initial development and maintenance
Contributors - Thank you to all contributors who have helped improve this project

solution-forest / workflow-engine-core

Maintainers

Details