Workflows and stages.

A workflow describes one approval process. It has a name, a slug, and an ordered list of stages. Each stage defines its approvers and the rule for moving to the next stage.

Workflows and stages are Eloquent models. Your application can create and edit them through its own management screens.

use ByRcsc\LaravelApproval\Models\ApprovalWorkflow;

$workflow = ApprovalWorkflow::create([
    'name' => 'Purchase orders',
    'slug' => 'purchase-order',
    'description' => 'Finance, then the board above ₱100,000.',
    'active' => true,
]);

Workflow slugs use one global namespace. Shared-database multi-tenant applications must scope lookups themselves or carry the tenant in each slug, for example acme:purchase-order.

Workflow columns

The approvable_type, condition, condition_config, and priority columns let one model use several workflows. You can leave them empty when the model has only one workflow. Choosing the workflow covers them in full.

Stage columns

$stage = $workflow->stages()->create([
    'sequence' => 1,
    'name' => 'Finance',
    'required_approvals' => 1,
    'rejection_policy' => RejectionPolicy::ApprovalImpossible,
    'sla_minutes' => 1440,
    'remind_every_minutes' => 240,
    'escalation_strategy' => EscalationAction::Escalate,
    'escalation_config' => ['resolver' => ManagerOf::class],
    'condition' => AmountExceeds::class,
    'condition_config' => ['threshold' => 100_000],
]);

Two stages of one workflow cannot share a sequence; the schema enforces it.

Approval thresholds

required_approvals expresses all three common rules:

A null value means every assignment must approve. The final number is known after any approver resolvers have run. Fluent definitions, array definitions, persisted rows, and request snapshots all treat an omitted value the same way.

A threshold higher than the number of assignments the stage can produce is a workflow that cannot reach a decision. Submission refuses it with InvalidWorkflowException before writing a row.

Rejection policy

The threshold says when a stage passes. The rejection policy says when it fails, and the two are configured separately.

approval_impossible is the default. On a 2-of-5 stage it lets three people say no before the stage is lost; on a unanimous stage it behaves like a veto, because one rejection already makes the threshold unreachable.

Rejection ends the whole request, not only the stage. Later stages that never ran are marked skipped rather than rejected. The requester may then revise and resubmit.

The snapshot boundary

Submission copies the following information onto the request:

• the workflow's stages, in order, with every column above;
• each stage's evaluated condition result; and
• the approval assignments, with resolvers already run.

From then on the request runs off its own copy. workflow_id on the request is a reporting reference only, and is nulled rather than cascaded if the workflow row is deleted, so history survives.

That means a workflow is freely editable. Adding a stage, changing a threshold, or replacing an approver affects what is submitted next and nothing already in flight. It also means a request can outlive the workflow that produced it.

When a reorganization genuinely must reach in-flight work, that is a deliberate administrative act: Approval::resync().

Deactivating a workflow

$workflow->update(['active' => false]);

An inactive workflow refuses new submissions with InvalidWorkflowException. Requests already running are unaffected because they hold their own snapshot.

Workflows soft-delete. A deleted workflow stops being found by Approval::workflow() while its requests keep their history.

Looking a workflow up

use ByRcsc\LaravelApproval\Facades\Approval;

Approval::workflow('purchase-order');       // throws if missing
Approval::findWorkflow('purchase-order');   // null if missing
Approval::workflowFor($order);              // applies the resolution order
Approval::workflowsFor($order);             // every workflow that applies
Approval::workflows();                      // every active workflow

workflowFor() resolves exactly as submission does: an argument wins outright, and otherwise candidates are gathered from the model's approvalWorkflow(), the approval.workflows config map, and the workflows registered against the model's type, then filtered by active state and condition. When nothing applies it throws WorkflowNotFoundException, and when two candidates are equally specific it throws AmbiguousWorkflowException. See choosing the workflow.

Reading a workflow's configured approvers

$workflow = ApprovalWorkflow::query()
    ->with('stages.approvers.approver')
    ->where('slug', 'purchase-order')
    ->firstOrFail();

$approversByStage = $workflow->stages->mapWithKeys(
    fn ($stage) => [
        $stage->sequence => $stage->approvers->map(
            fn ($entry) => $entry->approver ?? $entry->resolver,
        ),
    ],
);

Each value is either an approver model or a resolver class-string. A resolver needs the record, requester, and stage configuration before it can name the approvers. Those inputs become available during submission.

Per-workflow settings

The settings JSON column holds per-workflow overrides of package configuration. Currently one key is read:

$workflow->update(['settings' => ['allow_self_approval' => true]]);

This overrides approval.allow_self_approval for requests on this workflow. Unlike the stage rules, it is read live rather than snapshotted: tightening a control policy should apply to work already in flight.

What to read next

• Choosing the workflow to select between several workflows for one model.
• Approvers and resolvers to assign people, roles, or reporting lines.
• Conditional stages to skip stages based on the proposed model values.
• Submitting for approval to create requests from these workflow definitions.