Introduction.

Some model changes should not take effect as soon as someone submits them. A purchase order may need finance approval, followed by a director when its value crosses a limit. A supplier bank account change may need review from both the vendor management and finance teams before payments use the new details.

Laravel Approval stores that process in your database. You define the approval stages, assign the approvers, and submit an existing Eloquent model:

use ByRcsc\LaravelApproval\Concerns\Approvable;
use ByRcsc\LaravelApproval\Facades\Approval;

class PurchaseOrder extends Model
{
    use Approvable;
}

$request = $order->submitForApproval(
    'purchase-order',
    ['amount' => 10_000],
);

Approval::approve($request, $financeUser);

The proposed amount stays on the approval request until every required stage approves it. The package then writes the value to the purchase order.

Your application owns the screens, users, roles, and organization rules. The package manages the approval state, assignments, decisions, and history.

What an approval contains

A workflow defines the stages a request must pass through. Each stage defines who can respond and how many approvals it needs.

Submitting a model creates an approval request. The request receives a copy of the workflow, its stages, and its approvers. Later workflow edits affect new requests but do not change requests already in progress.

An approver can:

• approve the active stage;
• reject the request;
• return the request for revision.

Every action is recorded in an append-only history.

What can be approved

Approval requests always belong to records that already exist in the database. The package supports two common cases.

Approve the record. The request tracks whether people approve or reject the existing record. Your application decides what an approved state means for publication, visibility, or other business behavior.

Approve proposed attribute changes. Pass new attribute values during submission. The package holds them on the request and applies them after the final approval.

The package does not delay model creation. If a record should remain hidden or inactive while approval is pending, use request state or approval events in your application.

Main capabilities

• Ordered workflows with one or more approval stages.
• One-person, threshold, and unanimous approval rules.
• Direct approvers and resolvers for roles, teams, or reporting lines.
• Conditional workflows and stages.
• Attribute drafts with conflict detection.
• Returns, resubmission, delegation, reassignment, and bulk decisions.
• Deadlines, reminders, and escalation strategies.
• Queries for inboxes, progress, timelines, and authorization.
• Notifications, lifecycle events, factories, and testing helpers.
• An append-only action history with attachment evidence and verification.

Design boundaries

• An approver assignment names one actor. Use a resolver when a role or team should expand into several people.
• Each request keeps the workflow and approvers selected at submission time.
• A record can have only one unresolved request at a time.
• Approval mutations go through the Approval facade. The model provides the submission method because submission starts from that model.

Requirements

The package follows semantic versioning. You can upgrade within 1.x without breaking changes.

Source code and issues are available on GitHub.

What to read next

• Installation and setup to publish the configuration and database migration in the required order.
• Quick start to create and complete your first approval.
• Workflows and stages to choose approvers, thresholds, and rejection rules.