NewWe open-sourced 50+ Laravel packages
Custom AI apps, agents and automation — Roundly ConsultingRoundly
All packages
Workflows for Laravel

Bridges to other packages

A bridge is code for another Roundly package, active only when that package is installed. None is a runtime dependency: each is listed under suggest. A bridged step type whose package is missing stays in the catalogue with available: false and its package name, and publish reports adapter_missing. The whole package installs, boots and runs every built-in flow with no bridge at all.

PackageAdds
approvals-for-laravelThe approval step type (+ reassign escalations, exclude). Needs 2.2 or newer.
lifecycle-for-laravelThe default TransitionAdapter for the transition step; publish checks; optional transition events.
notifications-for-laravelThe notify step type and the notify escalation action, filed under the instance owner as inbox context.
opening-hours-for-laravelopening_hours:<name> business calendars. Needs 2.1 or newer.
forms-for-laravelForm-backed manual triggers.
teams-for-laravelOwner context, role parties, membership checks, subject ownership by team.
sentinel-for-laravelThe signature middleware for the inbound webhook route (configuration only).
webhooks-for-laravelThe workflows inbound handler (endpoint-wired webhook triggers) and the default deliverer of the webhook step.

Two bridges need a minimum version, enforced by Composer (conflict): approvals-for-laravel ≥ 2.2 (in-place stage hand-over since 2.1, excluding() since 2.2 — workflows 1.3.0 raised it from 2.1) and opening-hours-for-laravel ≥ 2.1 (addOpenDays() / addOpenTime()). An older installed version blocks composer require / update instead of failing at run time.

approvals — the approval step

// flat
{ "approvers": [ { "kind": "field", "field": "subject.approver" } ], "rule": "any", "expires_in": { "amount": 2, "unit": "business_days" } }
// staged
{ "stages": [ { "name": "Legal", "approvers": [ { "kind": "role", "role": "legal" } ], "rule": "unanimous" },
              { "name": "CFO",   "approvers": [ { "kind": "role", "role": "cfo" } ],   "rule": "any" } ],
  "expires_in": "P5D", "continue_on_rejection": false }
// an approvals preset (config approvals.workflows), approvers per stage
{ "preset": "payout", "approvers": [ [ { "kind": "field", "field": "subject.approver" } ] ] }
// any of the three, with parties who may never decide (since 1.3.0)
{ "approvers": [ { "kind": "role", "role": "cfo" } ], "rule": "any",
  "exclude": [ { "kind": "triggered_by" }, { "kind": "field", "field": "subject.requester" } ] }
  • Rules: unanimous, quorum (quorum, required), any, weighted — approvals’ own. Outcomes: approved, rejected, expired (required), cancelled (optional).
  • handle() resolves the parties per stage (nobody → fails no_approvers; never “anyone may decide”), computes the expiry in business time and opens the round once (a retry never opens a second). Output: {request_id, rounds, expires_at}. It waits for the round’s resolution plus a timer at expiry + approval.expiry_grace as a safety net, and probes once right after commit.
  • Several rounds may be open on one subject, so decide within the round — the step’s output.request_id, exposed by StepRunResource.
  • The resolution listener runs after the decider’s transaction commits and only signals: a decision that rolls back resumes nothing.
  • A round closed outside the workflow as cancelled takes the cancelled edge, else fails approval_cancelled. Cancelling the instance closes its open round — whether the step waits, is queued for a retry, or was still running. Only a pending round is closed; a decided one is left alone.
  • Reassign (escalation), once per escalation level: a staged round whose open stage has a name is handed over in place — the approvers who already decided stay named and their decisions keep counting, the undecided ones are replaced, the round keeps its absolute expiry and output.request_id doesn’t change. A flat round or an unnamed stage is replaced by a new round for the new parties with the original expiry; decisions on the old round don’t carry over. Name your stages to get the in-place hand-over.
  • A manual retry of a failed approval step keeps the same idempotency key, so it re-reads the round it already opened. Approval errors fail permanently (invalid_approval_request, unknown_approval_preset).
// Decide within the round the step opened — its output.request_id (exposed by StepRunResource)
Approvals::as($user)->for($subject)->within($round)->approve();

Excluded deciders (exclude, since 1.3.0) — a party list (user, field, role, triggered_by) of actors who may never decide the round, such as the requester approving their own request. It works with flat, staged and preset rounds:

  • The parties are resolved when the round opens (without the owner-membership filter) and handed to approvals’ excluding(): approvals stores them on the round, refuses their decision (UnauthorizedApprovalException), never asks them, never lets them act as a delegate, and lets no delegate decide for them.
  • They are also dropped from every approver list before the round opens. A list left empty fails no_approvers — never “anyone may decide”. Quorums and required are capped by the approvers that remain.
  • Reassign respects it: the target parties lose the excluded actors, whether the stage is replaced in place or a new round opens.
  • Publish validates exclude like any party list, and refuses an approver list (flat, a stage, a preset stage) whose every party also appears in exclude — approvers_excluded at that list’s path. An overlap that only shows at run time (a role whose only member is the starter) fails no_approvers.
  • Approvals writes the list to the guard columns of its 0008_add_decision_guards_to_approvals_tables migration; rounds without exclude never touch them, so run that migration before you publish a step with exclude.

lifecycle — the transition step and transition events

  • Lifecycles::for($subject, $lifecycle)->by($user)|asSystem()->because($reason)->idempotencyKey($key)->attempt($transition). Applied → transitioned. Denied → the denied edge, or fails transition_denied:<code>.
  • IdempotencyConflictException → idempotency_conflict; a lost race → retried; misuse (unknown lifecycle, trashed or unsaved subject) → transition_unusable.
  • Publish checks the transition exists (unknown_transition) and refuses set_field on a lifecycle state column (field_not_writable). The lifecycle history reason is workflow {key} v{n} #{instance ulid} (or the node’s reason).
  • Opt-in: with workflows.bridges.lifecycle.emit_transitions on, every lifecycle state change emits lifecycle.<lifecycle>.<transition> about the subject after its transaction commits — so a workflow can start (or a wait resume) when a record reaches a state, whoever moved it. An expiry or adoption uses its kind (lifecycle.purchase.expired). The payload is {lifecycle, transition, kind, from, to, history_id}, the actor is the triggering user, and the lifecycle history id is the idempotency key.
# every lifecycle state change emits lifecycle.<lifecycle>.<transition>
WORKFLOWS_LIFECYCLE_EMIT_TRANSITIONS=on

notifications — the notify step and escalation action

{ "notification": "purchase.approved", "recipients": [ { "kind": "field", "field": "subject.requester" } ],
  "data": { "amount": { "ref": "subject.amount" } }, "actor": "triggered_by" }

Notifications::send($type, $subject, $recipients, $data, $actor, $context, $idempotencyKey). Output {recipients: n}; nobody to notify completes with 0. Publish checks the type (unknown_notification_type) and the recipients. A refusal by notifications fails permanently as notification_refused:<notifications code> — never retried.

Inbox context (since 1.3.0): the step and the notify escalation action file their inbox items under the context workflows.bridges.notifications.context (WORKFLOWS_NOTIFICATIONS_CONTEXT) names:

ValueContext
ownerDefault; also blank, or the key missing from an older published config. The instance owner (Context::of($owner): key <alias>:<id>, label from notificationContextLabel(), else name); none for an owner-less instance.
off, none, null, falseNone — the 1.2 behaviour.
a ResolvesNotificationContext class-stringnotificationContext($instance, $owner, $subject) returns a Notifications\Context, a model, a context key string or null; anything else throws InvalidWorkflowsConfigurationException (the step fails exception).

An owner whose key the notifications context columns can’t hold (notifications.context_key_type, else notifications.key_type — say ULID teams with bigint contexts) is sent without a context rather than failing the send. Set the notifications context key type to the owner key type to get it filed.

opening-hours — calendars

opening_hours:<name> reads the owner’s opening-hours schedule <name> (open intervals, holidays, exceptions), and opening-hours does the business arithmetic itself: “2 business days” and “4 business hours” are counted exactly as opening-hours counts them, bounded by opening-hours.search_days. The owner model must implement OpeningHoursOwner (use HasOpeningHours) — workflows:doctor fails an active definition whose owner model lacks it. With teams, the owner is the team, so swap teams’ model for one that adds it:

// config/teams.php: 'models' => ['team' => App\Models\Team::class]
namespace App\Models;

use RoundlyConsulting\OpeningHours\Concerns\HasOpeningHours;
use RoundlyConsulting\OpeningHours\Contracts\OpeningHoursOwner;
use RoundlyConsulting\Teams\Models\Team as BaseTeam;

class Team extends BaseTeam implements OpeningHoursOwner
{
    use HasOpeningHours;
}

forms, teams and sentinel

  • forms — {"trigger": "manual", "form": "purchase-form"} validates input through forms-for-laravel; ->withForm($request, submit: true) stores a submission and puts its uuid in the trigger payload. Unknown form → unknown_form; a form trigger without forms installed → adapter_missing.
  • teams — steps of a team-owned instance run inside Teams::runAs($team), whatever context dispatched them; condition polls, escalations and a for_each schedule’s subject scan and its where too. {"kind": "role", "role": "legal"} resolves to the team’s active members with that role; user, field and triggered_by parties must be active members; BelongsToTeam / ScopedToTeam subjects are owned by their team.
  • sentinel — no code: set workflows.webhooks.verify_middleware = ['sentinel.signed:<profile>'] to check RFC 9421 signatures on the inbound webhook route.

webhooks — inbound endpoints and the webhook step

Webhooks for Laravel owns signatures, replay protection, retries, throttling, the SSRF guard, signing and the delivery log; the bridge wires it into workflows in both directions. Inbound: the bridge registers the handler alias workflows, and an inbound endpoint pointed at it starts the active workflow of the endpoint’s owner whose webhook trigger names the endpoint, keyed on the delivery id, so a replay never re-runs a workflow — the full rules are under Triggers. Outbound: the webhook step sends through webhooks’ sending API:

{ "type": "webhook", "config": {
    "endpoint": 12,
    "event": "invoice.approved",
    "payload": { "invoice": { "ref": "subject.number" }, "amount": { "ref": "subject.amount" } }
} }

// in PHP: ->webhook('send', $endpoint->id, 'invoice.approved', ['invoice' => Ref::subject('number')])
  • Registered when a DeliversWebhooks implementation is available: a container binding, workflows.adapters.webhooks, else this bridge. A host adapter takes over the whole step, and the webhooks event checks below then don’t apply.
  • The endpoint is an outbound endpoint id, looked up through webhooks in the instance owner’s scope (Webhooks::for($owner)->outbound()->find()); without an owner only owner-less endpoints are found. Owners must match exactly. Another owner’s endpoint, a missing one and an id that can’t be a key of webhooks’ primary_key_type all fail the step endpoint_not_found, with no query for a malformed id. endpoint is owner-specific: cleared and flagged on template import.
  • The payload is a map of values or refs resolved at run time, like start_workflow.input.
  • Exactly once: the send runs under $context->once('delivery'), and Webhooks::send() gets the step’s idempotency key as its id, so a retry of the visit queues nothing new, even where the once() record was lost. webhooks dispatches the delivery job after the transaction commits.
  • Outcome queued, output {delivery: "msg_…"} — the delivery’s id as webhooks’ delivery log shows it. The step completes when the delivery is queued; whether it arrives is webhooks’ job (retries, DeliveryFailed).
  • Publish checks through the bridge: the event must match webhooks’ event type rule (^[a-z0-9_]+(\.[a-z0-9_]+)*$, at most 100 characters), else invalid_config at /event; when webhooks’ outbound.event_types allow-list is set, the event must be in it, else unknown_webhook_event.
webhooks throwsStep fails withManual retry helps
EndpointNotFoundExceptionendpoint_not_foundno — missing, another owner’s or a malformed id
EndpointNotAcceptingExceptionendpoint_not_accepting:disabled / :not_subscribedyes, after enabling or subscribing the endpoint
InvalidEventTypeExceptioninvalid_event_typeno — e.g. the allow-list changed after publish
PayloadTooLargeExceptionpayload_too_largeno — over outbound.max_payload_bytes

None of these is retried automatically; anything else webhooks throws is a retryable exception. To deliver through your own service instead, implement Contracts\DeliversWebhooks (deliver(?Model $owner, string $endpoint, string $event, array $payload, string $idempotencyKey): int|string) — idempotent on the key — and name it in workflows.adapters.webhooks.

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.

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.