README

Simple, plugin-based workflow engine for PHP.

Requirements

PHP 8.2+
adachsoft/collection ^3.0

Installation

composer require adachsoft/workflow

Overview

The library provides two engines built around three central contracts:

WorkflowDefinitionRepositoryInterface
WorkflowRunRepositoryInterface
StepRegistryInterface

Available engines:

WorkflowEngineInterface for synchronous workflow execution
DebugEngineInterface for step-by-step workflow debugging

You can build ready-to-use default in-memory engines with:

WorkflowEngineBuilder
DebugEngineBuilder

Main Concepts

Step

A workflow step implements StepInterface and exposes its metadata through the #[StepType] attribute.

Workflow definition

A workflow definition is represented by WorkflowDefinitionVo. It stores workflow step configuration and determines the first step by the first defined key.

Workflow run

A workflow run is represented by WorkflowRunVo. It stores the current step, input, output, completion state, and optional debug state.

Payload

PayloadVo is an immutable value object used for step input, step config, and step output.

Basic Usage

use AdachSoft\Workflow\Attribute\StepType;
use AdachSoft\Workflow\Builder\WorkflowEngineBuilder;
use AdachSoft\Workflow\Contracts\StepInterface;
use AdachSoft\Workflow\Engine\PayloadVo;
use AdachSoft\Workflow\Engine\StepContextDto;
use AdachSoft\Workflow\Engine\StepResultDto;
use AdachSoft\Workflow\Engine\WorkflowDefinitionVo;
use AdachSoft\Workflow\Repository\InMemoryWorkflowDefinitionRepository;
use AdachSoft\Workflow\Repository\InMemoryWorkflowRunRepository;

#[StepType(type: 'finish', description: 'Ends the workflow')]
final class FinishStep implements StepInterface
{
    public function execute(StepContextDto $stepContextDto): StepResultDto
    {
        return StepResultDto::end(new PayloadVo(['status' => 'done']));
    }
}

$definitionRepository = new InMemoryWorkflowDefinitionRepository();
$runRepository = new InMemoryWorkflowRunRepository();

$workflowEngine = WorkflowEngineBuilder::create()
    ->withWorkflowDefinitionRepository($definitionRepository)
    ->withWorkflowRunRepository($runRepository)
    ->build();

$stepRegistry = (new ReflectionClass($workflowEngine))
    ->getProperty('stepRegistry')
    ->getValue($workflowEngine);
$stepRegistry->register(FinishStep::class);

$definitionRepository->save(new WorkflowDefinitionVo('example', [
    'finish' => new PayloadVo([
        'type' => 'finish',
        'config' => new PayloadVo(),
    ]),
]));

$runId = $workflowEngine->start('example', PayloadVo::empty());
$run = $runRepository->get($runId);

Builders

WorkflowEngineBuilder and DebugEngineBuilder provide two usage modes:

build a default in-memory engine
build an engine with custom repositories and a custom step registry

Example:

use AdachSoft\Workflow\Builder\DebugEngineBuilder;

$debugEngine = DebugEngineBuilder::create()->build();

Built-in Steps

The package currently provides these built-in steps in src/Steps:

RunWorkflowStep — starts another workflow and forwards the current input as output
SleepStep — pauses execution for a number of seconds within a configured limit

Builders can register the built-in steps for you:

$workflowEngine = WorkflowEngineBuilder::create()
    ->withStandardSteps()
    ->build();

Debug Engine

DebugEngineInterface supports:

starting a workflow in paused mode
starting from a selected step
executing one step at a time
pausing and resuming a run
reading the current run state

Step Metadata

The registry can expose all registered step definitions through StepRegistryInterface::getAllDefinitions().

This returns StepDefinitionCollection, which can be serialized to JSON with toJson().

Design Notes

Engines depend on contracts for repositories and the step registry.
Workflow execution is synchronous.
The debug engine executes one step at a time.
Public API uses value objects and collections instead of raw arrays where it matters.
Step metadata is centralized in the #[StepType] attribute.

Development

Available Composer scripts:

composer test
composer phpstan
composer cs-fix
composer cs-check

adachsoft / workflow

Maintainers

Package info

Statistics

Security