Laravel Approval Laravel Package

Product Decisions This Supports

• Build vs. buy for approval workflows. v1.0.0 is a complete, first-release approval engine. Unless approval flow is the product, this is the reference example of something to integrate rather than build: schema, state machine, authorization, audit, and SLA are all present, so the PM decision shifts from "can we build it?" to "which workflow do we configure first?"
• Workflow-configurable features over code. Version-controlled workflows defined in arrays or fluent builders, reconciled through approval:sync, mean product changes like adding a finance sign-off stage or changing an escalation window become configuration and release-management decisions, not engineering projects. Destructive drift is refused, so in-flight requests keep their snapshot — a defensible product guarantee to make to stakeholders.
• Multiple approval flows per entity. Several workflows per model with priority ordering and container-resolved conditions supports real product segmentation: different approval paths for expenses by amount, content by channel, contracts by counterparty type — without separate tables or bespoke code per flow.
• Auditable and defensible decisions. Per-request, hash-chained, append-only action history plus approval:verify supports product claims around traceability and tamper evidence. This is the feature that unlocks regulated or policy-sensitive domains (procurement, finance, HR, legal) where "who approved what, when" is a product requirement rather than a nice-to-have.
• SLA, reminders, and escalation as product promises. Per-stage deadlines with four configurable strategies, reminder cadence, stranded-stage detection, and idempotent escalation let product commit to turnaround times and auto-escalation behavior — and to not silently drop requests.
• Draft, conflict, and resubmission flows. Cast-aware stale checking, a conflicted state, and chained resubmission with a fresh workflow snapshot support the editing loop real approvers need, without silently overwriting someone else's changes.
• Draft-apply guard mode. Opt-in Eloquent protection for pending drafted attributes protects the "pending change" experience while keeping an audited escape hatch — a design that balances product safety with operational pragmatism.
• Delegation and recovery. Delegate/reassign, resync of live requests, preservation of assignment coverage on ownership changes, and orphan closure on hard delete support vacations, role changes, and offboarding — the operational realities that usually break approval features post-launch.
• Notifications and localization out of the box. Opt-in event map with commit-deferred delivery, publishable translations and mail views, and locale-aware messages mean product can own copy and localize without touching engine code.
• Testing support as a delivery accelerator. Exported factories and Approval::fake() with per-mutation assertions lower the cost of shipping approval-dependent features and reduce regression risk in adjacent product surfaces.
• Roadmap implications. Because the engine is solved, roadmap capacity moves to the differentiated layer: approval policies, policy authoring UX, reporting, integration with billing/ERP, and workflow design tooling.

When to Consider This Package

Adopt when:

• The application is Laravel 12 or 13 on PHP 8.3 or 8.4 and the team is comfortable with framework conventions rather than a separate service.
• Approvals are a supporting capability, not the core business — expenses, time off, content publishing, contract sign-off, access requests, procurement thresholds.
• Multiple entity types or multiple workflows per entity need approvals, with priority-based selection and conditional stages.
• Auditability, tamper evidence, and "why was I refused?" explainability are product or compliance requirements; the stable refusal reasons, policy-backed authorization, and approval:verify are directly usable here.
• Turnaround-time commitments exist and SLAs, reminders, and escalation need to be product-grade.
• Internationalization matters; publishable translations and mail views let copy be owned outside the engine.
• The team wants database portability (SQLite/MySQL/PostgreSQL tests) and multiple identity types (integer, UUID, ULID, string).
• Testability at the seam matters; Approval::fake() and coherent factories shorten delivery.

Look elsewhere or add a layer when:

• The architecture is not Laravel/PHP, or the organization mandates a standalone workflow service.
• Requirements call for BPMN-grade orchestration: parallel gateways, sub-processes, complex joins, cross-system compensation, long-running sagas.
• A no-code workflow designer for business users is a hard requirement — this package gives version-controlled code-adjacent definitions and a workflow picker query surface, not a visual builder.
• Approvals must run inside a certified third-party system (e.g., a validated QMS or an externally attested e-signature platform) where the audit chain's documented trust boundary is insufficient for the auditor.
• Very high-throughput, real-time collaborative approval experiences with presence, live cursors, or sub-second inbox updates are central — this is a transactional engine, not a realtime collaboration product.
• The product needs legal hold, retention policy management, and e-discovery export as first-class features; the append-only history is a foundation, not a records-management suite.
• The team cannot own migration and operational discipline for eight tables and scheduled commands (approval:escalate, approval:verify, approval:doctor), or has no appetite for running reconciliation via approval:sync as part of release process.

How to Pitch It (Stakeholders)

For executives: We are treating approval workflows as infrastructure, not a bespoke build. The first stable release delivers the full engine — configurable multi-stage workflows, conditional routing, delegation, SLAs with escalation, and a tamper-evident audit trail — as a versioned dependency. That converts a multi-quarter build into an integration and configuration effort, removes the largest source of "who approved this and why" risk, and lets us commit to turnaround times with automatic reminders and escalation. It also frees roadmap capacity for the parts customers actually differentiate on. Because workflows are version-controlled and in-flight requests keep their snapshots, changing an approval policy is a low-risk, release-managed operation rather than a data migration.

For engineering: The package is convention-driven and consistent with Laravel idioms: an Approvable trait, a container-resolved ApproverResolver contract with two built-in strategies, policy convention discovery, publishable translations and mail views, and config maps for escalation strategies. Correctness is engineered in — workflows that cannot reach a decision fail before any row is written; decisions run in per-request transactions with row locks; audit actions are append-only and hash-chained with a documented trust boundary and approval:verify. Draft apply does cast-aware stale checking, exposes a conflicted state, and keeps a final stale check as a backstop even under guard mode. Testability is first-class: exported factories for every model and Approval::fake() with a matching assertion per public mutation and no state writes. Quality bar is explicit — PHPStan at maximum level, Pint, tests across SQLite, MySQL, and PostgreSQL, string-identity coverage, PHP 8.3/8.4, Laravel 12/13. And workbench/ is a bootable demo app that exercises every integration seam end to end, so we can evaluate behavior before writing production code. Two operational notes to plan for: schedule approval:escalate and approval:verify, and treat approval:sync as part of the release process so workflow drift is caught deliberately rather than discovered in production.

Adoption recommendation: Proceed to a scoped pilot on one high-volume approval flow (e.g., expenses or content publishing), using the workbench as the reference integration, with an explicit review of the audit trust boundary against our compliance posture before extending to regulated flows.