Weave Code
Laravel Approval Laravel Package
byrcsc/laravel-approval
byrcsc/laravel-approval is a Laravel package for adding approval workflows to your application. Attach approvals to Eloquent models, manage pending and approved states, and keep approval logic organized within your existing Laravel app.
Multi-stage approval workflows for Laravel Eloquent models: database-driven stages, attribute drafts held until approval, approval thresholds, and a verifiable audit trail.
Frequently asked questions about Laravel Approval
- How do I install byrcsc/laravel-approval in a Laravel application?
- Install the package with Composer using composer require byrcsc/laravel-approval. Publish the migrations, translations, and mail views, then run your migrations to create the approval tables. Finally, add the Approvable trait to any Eloquent model that needs a workflow. The package ships a workbench app that demonstrates the full wiring if you want a working reference.
- Which Laravel and PHP versions does this approval package support?
- The package targets Laravel 12 and 13 and supports PHP 8.3 and 8.4. CI runs against SQLite, MySQL, and PostgreSQL, so the schema is exercised across the common Laravel database drivers. Check the repository for the exact constraints before upgrading your application.
- How do I attach an approval workflow to an existing Eloquent model?
- You add the Approvable trait to the model and define which workflow applies to it. The package owns the state machine and audit trail while your application keeps ownership of the model, the actors, and any attachment storage. You will also wire up an ApproverResolver and choose how workflows are selected for each model instance.
- What are attribute drafts and how does guard mode work?
- Attribute drafts hold pending changes to model attributes until the approval workflow reaches an approved state, so edited values are not written live before review. Guard mode is an opt-in Eloquent protection that prevents writes to pending drafted attributes, with a withoutApprovalGuard escape hatch that is audited. Treat the guard as a convenience rather than a guarantee, because the final stale check remains the backstop for writes that bypass model events.
- How are approval stages, thresholds, and conditional stages configured?
- Stages are database-driven and defined in version-controlled workflow definitions, so you can model flows like draft, submit, review, approve or reject, return, and resubmit. Approval thresholds let a stage require a certain level of sign-off before advancing. Conditional stages are resolved from the Laravel container, which keeps branching logic in dedicated classes instead of inside your models.
- Can I use UUIDs, ULIDs, or custom primary keys for approvers?
- Yes. The package supports integer, UUID, ULID, and string identities, which matters if your application is already locked into a primary key convention. Approver resolution goes through the ApproverResolver contract, and two resolver implementations ship with the package. Authorization is discovered by convention, so review the policy setup early if your naming does not match the defaults.
- How do I test approval workflows in my Laravel test suite?
- The package provides Approval::fake() plus exported factories so you can simulate approval states without building the full workflow by hand. This matters because approval state transitions are exactly the kind of logic teams tend to under-test. Combine the fake with your normal Laravel feature tests to cover submit, approve, reject, return, and resubmit paths.
- What does the approval:sync command do and how do I handle workflow drift?
- The approval:sync command reconciles your code-defined workflow definitions with the database. It is idempotent, supports a dry run, and refuses destructive drift, which is the safer default for running systems. Because in-flight approvals keep snapshots of their workflow, the running workflow and the code-defined workflow can legitimately diverge, so assign someone on your team to own that reconciliation.
- Is the audit trail tamper-proof for compliance use cases?
- The audit log is hash-chained, append-only, and enforced by the application, which makes it tamper-evident rather than tamper-proof. Anyone with direct database write access sits outside that boundary, and the package documents this explicitly. For regulated environments such as SOX, healthcare, or finance, surface this trust boundary to compliance reviewers early rather than at audit time.
- When should I avoid this package and use a simpler approach?
- If approval is a minor, incidental feature of your application, a boolean column plus a queued job is usually enough and far less to maintain. This package fits best when multi-stage approvals are a first-class product domain such as expense reports, content publishing, procurement, HR requests, or access grants. Also weigh the operational surface: eight tables, a policy, escalation strategies, notifications, and SLA scheduling all become things your team must understand and run.
Weaver
How can I help you explore Laravel packages today?