Download the PHP package solution-forest/workflow-engine-core without Composer

Workflow Engine Core

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

For Development

🚀 Quick Start

Basic Workflow Definition

Advanced Features

Conditional Steps

Retry Logic

Timeouts

🏗️ Architecture

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

📝 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

1. Builder → creates → Definition
2. Engine → uses Definition to create instances
3. Engine → delegates to Executor for step execution
4. Executor → runs → Steps & Actions
5. State Manager → persists → workflow state
6. 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:

Event Handling

Listen to workflow events:

Logging

Provide custom logging implementation:

🧪 Development

Testing

Run the test suite:

Code Quality

We use several tools to maintain high code quality:

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

🔗 Links

• Documentation
• Issues
• Changelog
• Laravel Integration