Quick Start

This example uses attribute-based definitions.

1. Generate a Workflow Skeleton

bin/cake workflow init order Orders

This creates a workflow directory in src/Workflow/Order/ with three files:

BaseOrderState.php

namespace App\Workflow\Order;

use Workflow\Attribute\StateMachine;
use Workflow\State\AbstractState;

#[StateMachine(name: 'order', table: 'Orders', field: 'state')]
abstract class BaseOrderState extends AbstractState
{
}

PendingState.php

namespace App\Workflow\Order;

use Workflow\Attribute\InitialState;
use Workflow\Attribute\Transition;

#[InitialState]
#[Transition(to: CompletedState::class, name: 'complete', happy: true)]
class PendingState extends BaseOrderState
{
}

CompletedState.php

namespace App\Workflow\Order;

use Workflow\Attribute\FinalState;

#[FinalState]
class CompletedState extends BaseOrderState
{
}

If Bake is installed, you can add more states later:

bin/cake bake workflow_state Order/Shipped --transition-to Delivered --transition-name deliver

See Attributes for adding guards, commands, and lifecycle callbacks.

2. Attach the Behavior

In your table class:

public function initialize(array $config): void
{
    parent::initialize($config);

    $this->addBehavior('Workflow.Workflow', [
        'workflow' => 'order',
    ]);
}

3. Apply Transitions

$order = $this->Orders->get($id);
$workflow = $this->workflowRegistry->get($order);

if ($workflow->can('complete')) {
    $result = $workflow->apply('complete', [
        'user_id' => $this->Authentication->getIdentity()->getIdentifier(),
        'reason' => 'Fulfillment finished',
    ]);

    if ($result->isSuccess()) {
        $this->Orders->saveOrFail($order);
    }
}

See Behavior Integration for the full API.

4. Inspect the Workflow

CLI:

bin/cake workflow list
bin/cake workflow show order
bin/cake workflow validate

Admin UI:

• /admin/workflow/workflows
• /admin/workflow/workflows/view/order

Next Steps

• Behavior Integration - Full behavior API reference
• Definitions - Explore definition formats in depth
• View Helper - Render diagrams, badges, and buttons in templates