Step handler contract
A step type is a class extending RoundlyConsulting\Workflows\Steps\StepType. It is both the catalogue entry (what a builder shows and validates) and the handler (what runs).
use RoundlyConsulting\Workflows\Steps\Schema\ConfigSchema;
use RoundlyConsulting\Workflows\Steps\StepContext;
use RoundlyConsulting\Workflows\Steps\StepResult;
use RoundlyConsulting\Workflows\Steps\StepType;
final class CreateTaskStep extends StepType
{
public function key(): string { return 'acme.create_task'; }
public function label(): string { return __('acme.workflows.create_task'); }
public function hasSideEffects(): bool { return true; }
public function ability(): ?string { return 'createTask'; }
public function configSchema(): array
{
return ConfigSchema::object()->string('title', required: true, maxLength: 200)->toArray();
}
public function handle(StepContext $context): StepResult
{
$taskId = $context->once('task', fn (): int => Task::create([
'title' => $context->config()['title'],
'subject_id' => $context->subject()?->getKey(),
])->id);
return StepResult::complete(output: ['task_id' => $taskId]);
}
public function simulate(StepContext $context): StepResult
{
return StepResult::complete(output: ['task_id' => null])
->wouldDo('Create task "'.$context->config()['title'].'"');
}
}Registration
// config/workflows.php
'steps' => [App\Workflows\CreateTaskStep::class],
// or at runtime, in a service provider
Workflows::catalogue()->register(CreateTaskStep::class);- Host keys must contain a dot (acme.create_task); un-dotted keys are reserved for the package: trigger, condition, branch, set_field, transition, delay, wait, loop, start_workflow, end, approval, notify, webhook.
- Registering the same class twice is a no-op; another class with the same key throws DuplicateStepTypeException. A bad key or an invalid config schema throws InvalidStepTypeException at registration (unsupported JSON-schema keywords, remote $refs and invalid patterns are refused there, naming the keyword).
- The catalogue is resolved lazily, so host providers that boot after the package still register in time.
Generate a starting point:
php artisan make:workflow-step CreateTicketStep
# app/Workflows/Steps/CreateTicketStep.php — key app.create_ticket, a label, side effects on,
# ability() returning null, a configSchema() with one required title string and a handle()
# that completes with empty output; register it with Workflows::catalogue()->register()The generated class is simpler than the example above: its handle() carries a comment pointing at once() and idempotencyKey(), and it has no simulate(). Add the once(), simulate() and ability() parts from the example yourself.
The class
| Method | Required | Meaning |
|---|---|---|
key(): string | yes | Catalogue key; host keys must contain a dot (acme.create_task). |
label(): string, description(): ?string, category(): string | label | Translated text for the UI. description() defaults to null, category() to custom. |
configSchema(): array | yes | JSON Schema subset; #/$defs/{value, party, parties, duration, condition, field} are provided. |
outcomes(array $config): list<Outcome> | default [Outcome::next()] | Outcome::of($key, required: true, label: null). May depend on config. |
outputSchema(): ?array | no | Lets publish validation check steps.<node>.output.<key> refs. |
hasSideEffects(): bool | yes | Side-effect types get the authorization hook, retries, idempotency keys and “would run” in dry runs. |
ability(): ?string | no | Policy ability the default authorizer checks on the subject before handle(). |
abilityFor(StepContext $context): ?string | no | The ability per run (default: ability()); set_field uses the subject type’s own. |
retry(): ?RetryPolicy | no | Type default retry policy. |
supportsEscalations(): bool | default false | escalations on a node of another type → invalid_config at /escalations. |
validateConfig(array $config, ValidationScope $scope): list<ValidationError> | no | Semantic checks beyond the schema; build errors with ValidationError::make(…). |
ownerSpecificPaths(): list<string> | no | JSON pointers cleared and flagged on template import; also derived from x-workflows-owner-specific: true. |
handle(StepContext $context): StepResult | yes | The work. |
resume(StepContext $context, Signal $signal): StepResult | types that wait on events or conditions | Called when a wait fires. The default completes a timer with next and a timeout with its outcome; any other signal fails resume_unsupported. |
simulate(StepContext $context): ?StepResult | no | Dry run. Must be pure. Absent on a side-effect type → “would run”. |
cancel(StepContext $context): void | no | Clean-up when the instance is cancelled while this step is live (waiting, queued for a retry or running). Make it idempotent. |
reassign(StepContext $context, list<PartyReference> $to): ?StepResult + supportsReassign(): bool | no | The reassign escalation action (default: none; publish refuses reassign on a type without it). |
cancel() details: an attempt that was running is cleaned up twice — once by the cancel (without its output) and once more when its result is recorded and discarded, with the output it returned, or, after a failed attempt or a worker that died, with none: read what once() committed with $context->recall().
Writing the config schema
ConfigSchema writes a schema with only the supported keywords, so a built schema always registers. Every method takes ?string $description and ?string $label (the title keyword, for builder forms). The schema is immutable — each call returns a new one:
use RoundlyConsulting\Workflows\Steps\Schema\ConfigSchema;
public function configSchema(): array
{
return ConfigSchema::object() // additionalProperties: false (object(true) allows more)
->string('title', required: true, maxLength: 200, label: 'Title')
->party('assignee', ownerSpecific: true) // flagged for review on template import
->enum('priority', ['low', 'normal', 'high'], default: 'normal')
->integer('estimate', min: 1, max: 40)
->list('tags', 'string', maxItems: 10)
->nested('meta', ConfigSchema::object()->string('source'))
->duration('due_in')
->nodeId('after') // another node's id, remapped on import
->toArray();
}| Method | Property |
|---|---|
string($name, required, minLength, maxLength, pattern, format, description, label) | {type: string, …} |
integer($name, required, min, max, …), number(…), boolean($name, required, default, …) | {type: integer|number|boolean, minimum?, maximum?} |
enum($name, list $values, required, default, …) | {enum, default?} |
list($name, ConfigSchema|string $items, required, minItems, maxItems, …) | {type: array, items} (a string is a JSON type) |
nested($name, ConfigSchema $schema, required, …) | A nested object (object() is the static entry point, so this one is nested()). |
value, party(…, ownerSpecific), parties(…, ownerSpecific), duration, condition, field | {$ref: "#/$defs/<name>"} (+ x-workflows-owner-specific: true) |
nodeId($name, …) | {type: string, format: node-id} |
What the engine guarantees
- One instance never advances twice in parallel. A handler never runs concurrently with another step of the same instance, as long as the worker enforces the job timeout (engine.lease − 30 s; needs pcntl) and the queue connection’s retry_after is longer than that timeout. Without pcntl a handler that outlives its lease can overlap its own retry. workflows:doctor checks both.
- $context->idempotencyKey() is stable across every attempt of the same visit: wf:{instance ulid}:{node id}:{visit} (≤ 100 chars, not a secret). It differs per visit, so a loop iteration is a new effect.
- Before handle(): the subject is loaded inside the instance’s owner context and checked against the owner; side-effect types passed the authorization hook; limits were checked.
What a handler must do
- Make every side effect idempotent on that key. For database effects use $context->once($name, Closure): it runs the closure and records its result in the same transaction, so a retry returns the stored result. Or store the key in a unique column. For external effects pass the key on (an HTTP Idempotency-Key, Notifications::send(idempotencyKey:), lifecycle’s idempotencyKey()). once() is exactly-once only for writes on the same database connection.
- $context->recall($name) reads what once($name) recorded for the visit without running anything (null if nothing) — for a cancel() hook whose attempt failed before it returned its output.
- Never sleep, poll or block. To wait, return StepResult::wait(WaitSpec).
- Keep no state between calls. Everything durable goes in output or in your own tables.
- Return plain-JSON output (scalars, lists, maps) ≤ steps_output.max_bytes (64 KiB). Models, objects, closures, INF/NAN → the attempt fails invalid_output (not retried).
- Authorize anything beyond the type’s ability() with $context->authorize($ability, $arguments). A denial fails the step authorization_denied (not retried).
Signalling failure
use RoundlyConsulting\Workflows\Steps\{RetryableStepException, StepFailedException};
throw StepFailedException::because('acme.task_board_closed', 'The task board is closed.'); // permanent
throw RetryableStepException::because('acme.rate_limited', 'Try again later.', now()->addMinute()); // retried
$context->authorize('assignTask', [$assignee]); // a denial fails the step authorization_denied (never retried)- StepFailedException::because($code, $message) — permanent.
- RetryableStepException::because($code, $message, ?CarbonInterface $retryAfter) — retried.
- Any other Throwable — retried, with error_code = exception. Its message is stored for operators (error_message, the step log in PHP, workflows:retry) but never rendered over the wire: the resources show the translated workflows::failures.exception instead, because framework messages routinely carry class names.
- Both because() methods take a FailureCode case or your own string code; your codes stay plain strings in WorkflowInstance::failure() / StepRun::error(). failureCode() and RetryableStepException::retryAfter() expose what the engine records.
- Either exception takes ->withDetails(array $details) (since 1.4.0), read back with details(): structured data the UI needs beside the code, such as an agent run’s id and stop reason — see Failure details.
StepResult and WaitSpec
| Constructor / builder | Meaning |
|---|---|
StepResult::complete(string $outcome = 'next', array $output = []) | Done; follow the edge for $outcome. |
StepResult::wait(WaitSpec $spec, array $output = []) | Park the step until the wait fires. |
StepResult::fail(string $code, string $message, ?array $details = null) | Permanent failure (same as StepFailedException). $details since 1.4.0 — see Failure details. |
->wouldDo(string $description, array $details = []) | In simulate(): an action a dry run lists. |
WaitSpec::until(CarbonInterface $at) | Fires at a time. |
WaitSpec::event(string $key, array $match = []) | Fires on emit()/signal() of the key. |
WaitSpec::condition(array $condition, ?Duration $poll = null) | Fires when the condition holds (on subject touch or poll). |
->timeout(Duration|CarbonInterface $after, string $outcome = 'timed_out') | Resumes with a timeout signal. |
->probe() | Resumes once right after commit (for waits that may already be satisfied). |
->alsoAt(CarbonInterface $at) | An extra timer (a safety net). |
StepResult is final readonly with isComplete(), isWait() and isFail(). A waiting step type — here one that sends a contract for e-signature, waits for the signed event and gives up after five days:
use RoundlyConsulting\Workflows\DataTransferObjects\Signal;
use RoundlyConsulting\Workflows\Enums\SignalKind;
use RoundlyConsulting\Workflows\Steps\{Outcome, StepContext, StepResult, WaitSpec};
public function outcomes(array $config): array
{
return [Outcome::of('signed'), Outcome::of('timed_out')];
}
public function supportsEscalations(): bool { return true; }
public function handle(StepContext $context): StepResult
{
$envelope = $context->once('envelope', fn (): string => $this->esign->send($context->subject(), $context->idempotencyKey()));
return StepResult::wait(
WaitSpec::event('contract.signed')->timeout($context->now()->addDays(5)),
output: ['envelope' => $envelope],
);
}
public function resume(StepContext $context, Signal $signal): StepResult
{
if ($signal->kind === SignalKind::Event) {
return StepResult::complete('signed', output: ['signed_by' => $signal->payload['by'] ?? null]);
}
return parent::resume($context, $signal); // a timer completes with next, a timeout with timed_out
}A step that uses ->probe() must re-read its source of truth in resume() (the child’s status, the round’s state), never trust the signal kind alone. A signal that lands while the probe runs stays claimed and is delivered afterwards, but a probe that fails transiently is retried as a probe — reading the source again is what makes both paths reach the same answer.
Failure details
Since 1.4.0. A failure can carry a small JSON object beside its code and message. Use it for data a UI links to or shows, so you never encode it into the code string (agent_run_failed:max_turns:01JD…). A failed StepResult carries failureCode, failureMessage and failureDetails (normalised, or null); the exceptions expose details():
public function handle(StepContext $context): StepResult
{
$run = $this->agents->run($context->config()['agent'], idempotencyKey: $context->idempotencyKey());
if ($run->failed()) {
return StepResult::fail('agent_run_failed', 'The agent stopped before it finished.', [
'run_id' => $run->id,
'stop_reason' => $run->stopReason,
]);
}
return StepResult::complete(output: ['run_id' => $run->id]);
}
// or, from deeper in your code:
throw StepFailedException::because('agent_run_failed', 'The agent stopped.')
->withDetails(['run_id' => $run->id, 'stop_reason' => $run->stopReason]);
// a transient failure: each attempt keeps its own details
throw RetryableStepException::because('agent_busy', 'The agent is busy.', $retryAt)
->withDetails(['run_id' => $run->id]);- The attempt: workflow_step_runs.error_details, StepRun::errorDetails(), StepRunResource error.details and the StepFailed event’s $details. Every attempt keeps its own.
- The instance, when the failure fails it (a permanent failure, or the last retry): workflow_instances.failure_details, WorkflowInstance::failureDetails(), InstanceResource failure.details and the InstanceFailed event’s $details. A manual retry clears them.
- Not in the owner export (Workflows::owners()->export()): it leaves out failure details, as it leaves out failure messages, inputs and outputs.
- The values come back as stored, but the order of an object’s keys is not guaranteed — MySQL’s json column sorts them. Compare stored details by key, not by position (Pest’s toEqual).
- A failure without details reads details: null everywhere — every failure recorded before 1.4.0, the package’s own failure codes and an unknown exception included.
The details are checked once, when you call fail() or withDetails(), so the stored row, the API and the events all hold the same value:
| Rule | What happens |
|---|---|
| A JSON object of plain values: strings, ints, finite floats, bools, null and nested lists and maps, at most 32 levels deep. | Anything else — an object, a model, a closure, a resource, INF/NAN, deeper nesting, a list at the top — is refused with InvalidFailureDetailsException (invalid_failure_details, 500); the message names the path, never the value. Inside a handler that is a coding mistake, so the step fails permanently with that code and is not retried. |
| Keys that name a secret | Redacted to "[redacted]" at any depth (a nested map or list under such a key goes whole). Keys split into words on separators and camelCase; a secret is any word password, passwd, pwd, passphrase, secret(s), credential(s), cookie(s), authorization, apikey, privatekey, bearer, otp, cvv, cvc or dsn; a last word token (access_token, idToken — not input_tokens or token_count) or auth (basic_auth); key after api, private, secret, access, signing, encryption, client, master, license, session or auth (api_key, X-Api-Key — not cache_key or idempotency_key); and session_id. It goes by key name only, so never put a secret under an innocent key. |
| Larger than workflows.failure_details.max_bytes (default 4 KiB, JSON-encoded after redaction) | Truncated to {"truncated": true, "bytes": n}, the marker an oversized step input gets. It never throws, because the size depends on runtime data — keep details to ids and short reasons. |
| Invalid UTF-8 | Repaired to U+FFFD, so writing the row never fails. |
| [] / null | No details (null). |
In tests: expect($instance)->toHaveFailedWith('agent_run_failed', ['run_id' => …, 'stop_reason' => …]). StepResult::fail() with bad details throws right in your unit test.
StepContext
- Reads: instance(), stepRun(), node(), graph(), version(), definitionKey(), config() (schema-validated), subject(), owner(), actor(), input(), trigger(), output(string $nodeId), resolve(mixed $valueOrRef), field(string $path), parties(list<PartyReference>), idempotencyKey(), attempt(), visit(), now(), timezone(), calendar(?string $name), defaultCalendar(), signal() (in resume()), simulating().
- Effects: authorize(string $ability, array $arguments = []) (skipped while simulating) and once(string $name, Closure $callback) (returns null while simulating); recall(string $name) reads a recorded once() result without running anything (null when none, or while simulating).
- The recorded input: before the handler runs, each attempt records step_runs.input — the node config with every value reference resolved at that moment: literals verbatim, refs and relatives resolved, models as {id, type}, field and triggered_by parties with the resolved person’s {id, type} added (role parties stay as written). Over steps_input.max_bytes it is {"truncated": true, "bytes": n}. A retry records its own input; a resume keeps it. Keep secrets out of node configs and refs: the input is stored and rendered by StepRunResource.
ValidationScope
What validateConfig() checks against (final readonly): graph, node, subjectType and ownerType (?SubjectTypeDefinition), owner, inputs (declared trigger inputs, name → FieldType), definitionKey; forNode(Node $node) and isAncestor(string $nodeId) — whether that node runs before this one on every path, so its output may be referenced. Build errors with ValidationError::make(ValidationCode, node:, path:, params:).
The config schema subset
Draft 2020-12, so a UI can feed the exported schemas to any JSON-schema form renderer. Errors come back as ValidationError(code: invalid_config, node, path: JSON pointer, params: {keyword, expected}). Depth and total checks are bounded, so a pathological schema can’t hang publish:
- type (one or a list), enum, const.
- properties, required, additionalProperties (bool or schema), items, minItems, maxItems, uniqueItems.
- minLength, maxLength, minimum, maximum, exclusiveMinimum, exclusiveMaximum, multipleOf.
- pattern (host-authored; compiled once, length-guarded).
- oneOf, anyOf, allOf, $defs, local $ref (#/$defs/… only).
- format: date, date-time, duration, timezone, cron, field-path, node-id.
- Carried through untouched: title, description, default, examples, x-workflows-* (x-workflows-field-types, x-workflows-owner-specific), and since 1.4.0 the annotation prefixes listed in workflows.schema.extension_prefixes (e.g. ['x-acme-'], so x-acme-agent-picker is allowed). Annotations are exported with the catalogue and never validated; any other x-… keyword is refused at registration (unsupported_schema_keyword).
Show your open-source love
This package is free and MIT-licensed. If it saves you time, a one-off donation or a Patreon membership keeps it maintained, tested and documented.
More ways to support, including cryptoBy donating, you agree to our donation terms.
Want this built into your product?
We integrate our packages into custom Laravel and AI builds. Tell us what you're working on and we'll reply within 48 hours.