Workflow Handler Registry
Contract for registering workflow action handlers under their persisted identifiers and resolving them through the container.
Overview
App\Services\Workflows\WorkflowHandlerRegistry maps the action identifiers persisted on workflow steps to App\Contracts\Workflows\WorkflowHandler implementations.
WorkflowServiceProvider binds the registry as a singleton constructed with the application container. Core registers its own handlers on boot; plugins register additional handlers through PluginRegistrar::workflowHandler().
Identity is deliberately absent from the handler contract itself. A handler describes and executes an action; the identifier under which that action is persisted belongs to the registry, so the same handler class can be registered under a different identifier without editing it.
Public surface
| Method | Purpose |
|---|---|
register() |
Register one typed handler class under a new identifier |
registerPluginManifest() |
Register the manifest-declared handlers owned by a plugin |
replacePluginManifest() |
Atomically replace a plugin's handler declarations |
removePlugin() |
Remove handler registrations owned by a plugin |
registerInvocableAction() |
Register an invocable action class under an identifier |
get() |
Resolve one typed handler by identifier or throw |
getByType() |
Resolve a typed handler by its type and version |
getClass() |
Return the registered class for an identifier |
getDeclaration() |
Return normalized declaration metadata |
getPinned() |
Resolve a retained handler by its complete version and plugin pin |
getPinnedClass() |
Return the retained handler class for a complete pin |
getPinnedDeclaration() |
Return normalized declaration metadata for a complete pin |
getRegistrationMetadata() |
Return registration metadata for an identifier |
retainPinned() |
Validate and retain a handler needed by an admitted workflow run |
restorePinned() |
Rehydrate a retained handler from trusted persisted metadata |
catalogue() |
Return declarations keyed by identifier |
allDeclarations() |
Return all registered declarations |
invocableActionClasses() |
Return invocable action classes keyed by identifier |
resolveObject() |
Resolve a registered class through the container |
has() |
Check whether an identifier is registered |
all() |
Resolve every typed handler, keyed by identifier |
Accepted contract
The registered value is a class-string for a WorkflowHandler implementation, which requires:
name(): string— human-readable name shown when building a workflowdescription(): string— short explanation of the action's behaviourgroup(): string— logical group used by workflow-builder presentationconfigSchema(): Schema— declarative configuration schema for the actionoutputs(): array— possible outputs keyed by paths relative to the action's resultexecute(WorkflowHandlerContext $context): WorkflowHandlerResult— run the action
Handler failures are represented by exceptions rather than by a failure result value, so the execution engine can apply its own failure policy.
Identity, collisions, and construction
register() validates eagerly and refuses to overwrite. It throws InvalidArgumentException for a blank identifier, for a class that does not exist or does not implement WorkflowHandler, and for a class that is not instantiable; it throws LogicException when the identifier is already registered.
Rejecting duplicates rather than replacing them is the important property: identifiers are persisted on saved workflows, so a silent replacement would change what an existing workflow step does at its next execution.
The registry records class strings, not handler objects. get() and all() resolve through the container on every call, so handler dependencies stay injectable and test doubles can replace concrete classes through the container. A resolved object that does not implement WorkflowHandler raises LogicException.
Failure behaviour
get($identifier) throws InvalidArgumentException with Unknown workflow handler [{identifier}]. when nothing is registered under that identifier. all() shares the resolution path, so a definition whose class cannot be built surfaces the container's own failure.
Plugin registration
PluginRegistrar::workflowHandler($identifier, $handlerClass) is the plugin-facing entry point. Handler identifiers are global and persisted, so a plugin-scoped registrar requires the identifier to carry the plugin's vendor prefix — the same rule the manifest validator applies to permission, event, and datatable keys. Core identifiers are unprefixed, which is what prevents a plugin from shadowing or replacing a core handler. registerPluginManifest(), replacePluginManifest(), and removePlugin() keep manifest-owned registrations versioned and isolated for plugin lifecycle operations; getRegistrationMetadata() exposes the owning package and declaration metadata for diagnostics.
Admitted workflow runs may outlive the active plugin registration that produced them. retainPinned() validates and records that exact handler contract, while restorePinned() rebuilds it from trusted durable metadata after a process restart. getPinned(), getPinnedClass(), and getPinnedDeclaration() resolve only an exact identifier, handler version, plugin package, and plugin-version match; retained handlers are never made eligible for new publication.
Registry validation failures surface from the registrar as PluginRegistrarException naming the package responsible, with the registry's own exception as the preceding exception. Unscoped registrars — core and tests — are not prefix-gated.
Worked example
Registering a handler and executing it by its persisted identifier:
$registry = app(WorkflowHandlerRegistry::class);
$registry->register('send_email', SendEmailHandler::class);
if ($registry->has($step->action)) {
$result = $registry->get($step->action)->execute($context);
}
all() returns the same resolved objects keyed by identifier, which is what a workflow builder consumes when it lists the available actions with their names, groups, config schemas, and outputs.