DI and actions

The facade is the recommended default, not the only way in. Every operation is an action, the manager exposes each one and the facade is sugar over the manager — all three run the same code. The manager is RoundlyConsulting\Workflows\WorkflowsManager, the facade’s root, bound as a container singleton and injectable by its class-string:

use RoundlyConsulting\Workflows\Actions\Instances\StartInstanceAction;
use RoundlyConsulting\Workflows\DataTransferObjects\StartData;
use RoundlyConsulting\Workflows\Facades\Workflows;
use RoundlyConsulting\Workflows\WorkflowsManager;

// Facade
$result = Workflows::start('purchase-approval', $request, $team)->input(['reason' => 'laptops'])->by($user)->dispatch();

// Dependency injection — the same API
public function __construct(private WorkflowsManager $workflows) {}
$result = $this->workflows->start('purchase-approval', $request, $team)->input(['reason' => 'laptops'])->by($user)->dispatch();

// The raw action (not recorded by the fake)
$result = app(StartInstanceAction::class)->execute(new StartData('purchase-approval', $request, $team, ['reason' => 'laptops'], $user));

The HasWorkflows trait is a fourth entry point to the same manager — $request->workflows()->start('purchase-approval')->dispatch() delegates to it, so the fake sees those calls too.

Inject the manager

use RoundlyConsulting\Workflows\Exceptions\WorkflowsException;
use RoundlyConsulting\Workflows\WorkflowsManager;

final class RetryWorkflowController
{
    public function __invoke(WorkflowsManager $workflows, string $ulid)
    {
        $instance = $workflows->instances()->find($ulid) ?? abort(404);

        try {
            $workflows->instances()->retry($instance);
        } catch (WorkflowsException $e) {
            return response()->json(['code' => $e->errorCode(), 'message' => $e->getMessage()], $e->status());
        }

        return response()->noContent();
    }
}

Workflows::fake() swaps in Testing\WorkflowsFake — a subclass of the manager — behind the facade and in the container, so code that injects WorkflowsManager is faked too.

Call an action

Every operation is a final readonly action with one execute(), resolved through the container — bind your own subclass to override one. Raw action calls are not recorded by the fake; host code normally calls the facade or the manager:

use RoundlyConsulting\Workflows\Actions\Instances\RetryInstanceAction;
use RoundlyConsulting\Workflows\Actions\Versions\DiffVersionsAction;

app(RetryInstanceAction::class)->execute($instance);

$diff = app(DiffVersionsAction::class)->execute($v2, $v3);   // VersionDiff

Facade method → action

Namespaces are relative to RoundlyConsulting\Workflows\Actions:

Action	execute(…)	Facade path
`Definitions\CreateDefinitionAction`	`(CreateDefinitionData $data): WorkflowDefinition`	`definitions()->create() / createWith()`
`Definitions\RestoreDefinitionAction`	`(string $key, ?Model $owner): WorkflowDefinition`	`definitions()->restore()`
`Definitions\SyncDefinitionsAction`	`(string $path, ?Model $owner = null, bool $publish = false, bool $dryRun = false): SyncReport`	`definitions()->sync()`
`Definitions\SaveDraftAction`	`(WorkflowDefinition $definition, array $graph, ?string $expectedChecksum = null): WorkflowVersion`	`definition()->edit()`
`Definitions\DiscardDraftAction`	`(WorkflowDefinition $definition): WorkflowDefinition`	`definition()->discardDraft()`
`Definitions\PublishVersionAction`	`(WorkflowDefinition $definition, ?Model $by = null): WorkflowVersion`	`definition()->publish()`
`Definitions\RetireDefinitionAction`	`(WorkflowDefinition $definition): WorkflowDefinition`	`definition()->retire()`
`Definitions\ActivateDefinitionAction`	`(WorkflowDefinition $definition): WorkflowDefinition`	`definition()->activate()`
`Definitions\ResolveReviewFlagAction`	`(WorkflowDefinition $definition, string $node, string $path): WorkflowVersion`	`definition()->resolveFlag()`
`Definitions\RotateWebhookAction`	`(WorkflowDefinition $definition): WorkflowDefinition`	`definition()->rotateWebhook()`
`Versions\ValidateGraphAction`	`(array $graph, ?string $subjectType = null, ?Model $owner = null, array $reviewFlags = [], ?string $definitionKey = null): ValidationReport`	`versions()->validate(), definition()->validate(), GraphBuilder::validate()`
`Versions\DiffVersionsAction`	`(WorkflowVersion $from, WorkflowVersion $to): VersionDiff`	`versions()->diff()`
`Versions\OverlayAction`	`(WorkflowVersion $version): OverlayReport`	`versions()->overlay()`
`Versions\ExportTemplateAction`	`(WorkflowVersion $version): TemplatePayload`	`versions()->export(), definition()->export()`
`Versions\ImportTemplateAction`	`(TemplatePayload\|array $payload, ?Model $owner = null, ?string $key = null): ImportResult`	`versions()->import()`
`DryRun\DryRunAction`	`(DryRunData $data): DryRunResult`	`PendingDryRun::run() / explore()`
`Instances\StartInstanceAction`	`(StartData $data): StartResult`	`start()->dispatch(), startWith(), for()->start(), definition()->start()`
`Instances\EmitEventAction`	`(EmitData $data): EmitResult`	`emit(), emitWith(), for()->emit()`
`Instances\ReceiveWebhookAction`	`(string $hookId, array $payload, array $headers = []): StartResult`	`triggers()->webhook() and the inbound route`
`Instances\RetryInstanceAction`	`(WorkflowInstance $instance): WorkflowInstance`	`instances()->retry()`
`Instances\CancelInstanceAction`	`(WorkflowInstance $instance, ?string $reason = null): WorkflowInstance`	`instances()->cancel(), for()->cancelAll()`
`Instances\TouchSubjectAction`	`(Model $subject): int`	`for()->touch()`
`Wake\WakeAction`	`(?CarbonInterface $now = null, ?int $limit = null): WakeReport`	`wake()`
`Maintenance\PruneAction`	`(): PruneReport`	`prune()`

Internal (the engine’s own building blocks, never called by host code): Engine\RunStepAction, Engine\ResumeStepAction, Engine\RecordStepResultAction, Engine\FireEscalationAction, Instances\SignalAction, Wake\EvaluateSchedulesAction, Wake\ReclaimAction.

Contracts you may implement

Contract	Methods	Default / where it plugs in
`AuthorizesSteps`	`authorize(StepAuthorization $authorization): Response`	GateStepAuthorizer; authorization.authorizer
`RestoresOwnerContext`	`run(?Model $owner, Closure $callback): mixed`	Teams bridge, else NullOwnerContext; owners.context
`ChecksOwnerMembership`	`isMember(?Model $owner, Model $user): bool`	Teams bridge, else allow-all; owners.membership
`ResolvesRoles`	`members(?Model $owner, string $role): array`	Teams bridge, else none; parties.roles
`TransitionAdapter`	`attempt(…): TransitionOutcome; hasTransition(…): ?bool; stateAttributes(string $subjectClass): array`	Lifecycle bridge, else none; adapters.transition
`DeliversWebhooks`	`deliver(?Model $owner, string $endpoint, string $event, array $payload, string $idempotencyKey): int\|string`	None; adapters.webhooks registers the webhook step
`BusinessCalendar`	`timezone(), isBusinessDay($date), isOpenAt($instant), nextOpen($instant), nextClose($instant)`	weekdays, opening_hours:*; Workflows::calendars()->register()
`CountsBusinessTime`	`addBusinessDays(CarbonImmutable $from, int $days), addBusinessTime(CarbonImmutable $from, int $seconds)`	Optional on a calendar that does its own arithmetic (opening-hours calendars do).
`HasWorkflowOwner`	`workflowOwner(): ?Model`	On a subject model: its owner, checked first.
`DescribesWorkflowSubject`	`describe(): SubjectTypeBuilder`	Classes listed in workflows.subjects.
`WorkflowEvent`	`workflowKey(), workflowSubject(), workflowPayload(), workflowUser(), workflowIdempotencyKey()`	A self-describing host event (listen() or '*').

A container binding of AuthorizesSteps, RestoresOwnerContext or ChecksOwnerMembership registered after the package’s provider wins over the config class.

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 crypto

By donating, you agree to our donation terms.

Support our open source work Join us on Patreon

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.

Get a quote in 48 hours Browse all packages