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 93 tests and 224+ assertions

📦 Installation

For Production Use

For Development

🚀 Quick Start

Basic Workflow Definition

Advanced Workflow Builder

PHP 8.3+ Attributes

Note: Attributes are currently metadata annotations for documentation and tooling. They are not yet auto-parsed by the engine at runtime — use the builder API (timeout:, retryAttempts:, when()) or step config to apply these behaviors. Attribute-driven execution is planned for a future release.

Use native PHP attributes to annotate actions with retry, timeout, and conditions:

Retry Logic

Timeouts

Conditional Execution

Step Metadata

Retry, Timeout & Conditions via Builder

These features can also be configured through the fluent builder API:

Condition Syntax

Conditions are parsed, never eval()'d. The same grammar is used by step conditions, transition conditions, when() and ConditionAction.

Dot notation reads nested data (order.customer.email). Values may be numbers, quoted strings, bare words, true, false or null.

Two rules keep a mistyped condition from quietly routing a workflow the wrong way:

• A malformed expression throws InvalidWorkflowDefinitionException rather than collapsing to a boolean. Chained comparisons (a > 1 > 2), dangling operators and unbalanced parentheses are all rejected.
• A relational comparison against a missing key is false. Because null coerces to 0 in PHP, missing.key < 1000 would otherwise be true and a step gated on data that was never set would run.

Workflow Lifecycle Management

SimpleWorkflow Helper

For quick workflow execution without manual engine setup:

🏗️ Architecture

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

Core Components

State Machine

Valid transitions:

• PENDING → RUNNING, FAILED, CANCELLED
• RUNNING → WAITING, PAUSED, COMPLETED, FAILED, CANCELLED
• WAITING → RUNNING, FAILED, CANCELLED
• PAUSED → RUNNING, FAILED, CANCELLED
• FAILED → RUNNING (via resume()), CANCELLED
• Terminal states (COMPLETED, CANCELLED) → no further transitions

FAILED is recoverable, not terminal: calling resume() puts the instance back into RUNNING and retries the step that failed, which is how you recover a workflow once the underlying cause is fixed.

A workflow whose next steps are all blocked on unmet prerequisites parks in WAITING rather than sitting in RUNNING, so a stuck instance is distinguishable from one still executing.

State transitions are validated at runtime — invalid transitions throw InvalidWorkflowStateException.

Namespace Map

Built-in Actions

Six ready-to-use actions are included:

WorkflowState Helpers

The WorkflowState enum provides utility methods for UI and logic:

🔧 Configuration

Storage Adapters

Implement the StorageAdapter interface for custom persistence:

Event Handling

Listen to workflow events — 7 event types are dispatched during execution:

Logging

Provide a custom logging implementation (PSR-3 style):

🧪 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 zero errors across 46 source files
• Laravel Pint - Consistent code formatting following Laravel standards
• Comprehensive Testing - 93 tests with 224+ assertions covering unit, integration, and real-world scenarios
• Architecture Tests - Automated checks preventing debug functions in source code
• State Transition Validation - Runtime enforcement of valid workflow state transitions
• Type Safety - Full PHP 8.3+ type declarations throughout
• Continuous Integration - Automated quality checks on every commit (PHP 8.3/8.4 matrix)

📚 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

• Issues
• Changelog
• Laravel Integration