README

Part of the Jardis Business Platform — Enterprise-grade PHP components for Domain-Driven Design

Directed workflow engine for multi-step process orchestration. Define handler graphs with status-based transitions, automatic data accumulation between steps, and a fluent builder API. Each handler returns a WorkflowResult that determines the next step.

Features

Directed Handler Graph — connect handlers as nodes with explicit per-status transitions
Status-Based Transitions — onSuccess, onFail, onRetry, onSkip, onCancel, onTimeout, onError, onPending
Automatic Data Accumulation — each handler's result array is merged into a shared context passed to subsequent handlers
Fluent Builder API — WorkflowBuilder + WorkflowNodeBuilder wire the graph without configuration arrays
Handler Factory — inject a closure to resolve handlers from a DI container
Full Call Stack Recording — the result contains every executed handler name mapped to its WorkflowResult
WorkflowResult — typed value object with status constants; no ambiguous truthy/falsy returns

Installation

composer require jardissupport/workflow

Quick Start

use JardisSupport\Workflow\Builder\WorkflowBuilder;
use JardisSupport\Workflow\Workflow;
use JardisSupport\Workflow\WorkflowResult;

// Build a two-step graph
$config = (new WorkflowBuilder())
    ->node(ValidateOrderHandler::class)
        ->onSuccess(ChargePaymentHandler::class)
        ->onFail(RejectOrderHandler::class)
    ->node(ChargePaymentHandler::class)
        ->onSuccess(ConfirmOrderHandler::class)
    ->build();

$workflow = new Workflow();
$output = $workflow($config, $order);

echo $output['result']['orderId'];      // accumulated data
echo count($output['callStack']);        // number of handlers executed

Advanced Usage

use JardisSupport\Workflow\Builder\WorkflowBuilder;
use JardisSupport\Workflow\Workflow;
use JardisSupport\Workflow\WorkflowResult;

// Handler using named transitions (retry loop)
class ChargePaymentHandler
{
    public function __invoke(Order $order, array $accumulated): WorkflowResult
    {
        $result = $this->gateway->charge($order->total);

        if ($result->isTemporaryFailure()) {
            return new WorkflowResult(WorkflowResult::ON_RETRY, ['attempt' => $accumulated['attempt'] + 1]);
        }

        if (!$result->isSuccess()) {
            return new WorkflowResult(WorkflowResult::STATUS_FAIL, ['error' => $result->message]);
        }

        return new WorkflowResult(WorkflowResult::STATUS_SUCCESS, ['chargeId' => $result->id]);
    }
}

// Wire retry back to the same handler
$config = (new WorkflowBuilder())
    ->node(ChargePaymentHandler::class)
        ->onSuccess(FulfillOrderHandler::class)
        ->onFail(NotifyFailureHandler::class)
        ->onRetry(ChargePaymentHandler::class)   // loop back
    ->build();

// Inject handlers from a DI container
$workflow = new Workflow(fn(string $class) => $container->get($class));

$output = $workflow($config, $order, ['attempt' => 0]);

// Inspect the call stack
foreach ($output['callStack'] as $handlerName => $result) {
    echo "{$handlerName}: {$result->getStatus()}\n";
}

Documentation

Full documentation, guides, and API reference:

docs.jardis.io/support/workflow

License

This package is licensed under the PolyForm Shield License 1.0.0. Free for all use except building competing frameworks or developer tooling.

Jardis · Documentation · Headgent

jardissupport / workflow

Maintainers

Package info

Statistics

Security