Hooks

The engine emits lifecycle events through an in-process HookDispatcher (a container singleton). The package uses it internally for execution logging and for resuming workflows waiting on a child. You can attach your own listeners for observability — metrics, tracing, alerting.

use Qanna\WorkflowEngine\Engine\HookDispatcher;

public function boot(): void
{
    $hooks = $this->app->make(HookDispatcher::class);

    $hooks->on('workflow.finished', function (string $workflowId, string $executionId, $status, ?string $error, $execution) {
        if ($status->value === 'failed') {
            // notify, record a metric, …
        }
    });
}

on($event, $callback, $priority = 100, $once = false) — lower priority runs first. once() registers a one-shot. off(), flush(), has(), count(), events() round out the API. A listener returning false halts further listeners for that event.

Events

Event	Arguments
`workflow.starting`	`$workflowId, $executionId`
`workflow.started`	`$workflowId, $executionId, $triggerOutput`
`workflow.resumed`	`$workflowId, $executionId`
`workflow.node-executing`	`$workflowId, $executionId, $nodeId`
`workflow.node-executed`	`$workflowId, $executionId, $nodeId, NodeResult $result`
`workflow.node-retrying`	`$workflowId, $executionId, $nodeId, array $meta`
`workflow.node-slow`	`$workflowId, $executionId, $nodeId, array $meta`
`workflow.finished`	`$workflowId, $executionId, ExecutionStatus $status, ?string $error, Execution $execution`
`workflow.completed`	`$workflowId, $executionId, WorkflowExecution $execution` — fired by the execution manager once a top-level run/resume is fully finalised (including scheduling).
`workflow.trigger-ignored`	`$workflowId, array $payload, ?string $reason`

workflow.node-executed fires for successful, failed, and errored node results alike — inspect the NodeResult.

These event names and payloads are not yet a formally frozen public API; treat them as stable-in-practice but verify after upgrades. For reacting to failures specifically, polling ExecutionRepositoryContract::listByStatus(Failed) is the more conservative choice.

Events​

Events