Guardrails

What is Guardrails?

Guardrails is an operational approvals engine for Laravel. Capture every high‑risk change, route it through the right reviewers, and apply the update only after the required signatures land. You decide which attributes are guarded, who can approve, and how many voices it takes to ship a change.

Why teams reach for Guardrails

• Protect critical workflows – turn dangerous writes into reviewable approval requests without rewriting business logic.
• Model or controller first – opt in with an Eloquent trait or intercept at the edge of your HTTP layer.
• Fluent, composable flows – stack steps, mix roles and permissions, count initiators, and codify escalation in code.
• Complete toolkit – ships with migrations, API routes, reviewer UI, and exhaustive docs so you can go live quickly.
• Laravel-native – PHP 8.2+, Laravel 11/12/13, works with Spatie permissions or Sanctum token abilities out of the box.

How it fits together

1. Mark attributes as guarded or intercept controller payloads.
2. Use Flow::make() / FlowBuilder to describe who can sign each step.
3. Guardrails persists the request (requests → steps → signatures) and emits events as people approve or reject.
4. Once the final step meets its threshold, Guardrails applies the captured changes to your model for you.

Quickstart

Online Docs & Tools

• Full documentation: https://ovac.github.io/guardrails/
• Interactive Playground (flow builder): https://ovac.github.io/guardrails/playground
• AI Assistant (BYO API key, grounded in docs): https://ovac.github.io/guardrails/assistant

Install via Composer:

1. Register the service provider (if not auto‑discovered):

2. Publish assets:

3. Run migrations:

60‑Second Example

Guard a model and require a quick two‑man rule (initiator + one peer):

When the initiator supplies a justification (for example through a form field), pass it into the guardrails context before saving:

Prefer controllers? Intercept without touching models:

Configurable controller flows (no code changes)

Keep controllers tiny and let ops override steps from config/guardrails.php. The helper will (a) look for guardrails.flows.<feature>.<action>, (b) fall back to your coded flow when missing, and (c) merge handy meta defaults (like summary/hint) onto every step.

Why Teams Use It

• Approval confidence for critical data while keeping code changes small.
• Human-readable flow rules with real-world patterns (two-man rule, peer review, escalation).
• Works with your auth today — Spatie permissions if present, token abilities otherwise.

Use Cases (with examples)

1) Publish a blog post — one more editor must approve

2) Delete a user account — two steps, different roles

3) Refund an order — one of finance OR operations

4) Sensitive setting change — peer with same permission must co‑sign

5) Multi‑step escalation — ops first, then execs

API (3 endpoints)

• GET /{route_prefix} — list pending approval requests with steps/signatures.
• POST /{route_prefix}/{request}/steps/{step}/approve — approve a step.
• POST /{route_prefix}/{request}/steps/{step}/reject — record a rejection signature.

UI

A minimal page at /{page_prefix} consumes the API for reviewers. Publish and customize the Blade view.

Docs

• Start here: Documentation Index
• Or publish locally: php artisan vendor:publish --provider="OVAC\\Guardrails\\GuardrailsServiceProvider" --tag=guardrails-docs (to docs/guardrails).

Highlights worth reading next:

• Organization Playbook
• Use Cases
• Advanced Flows (dynamic/risk‑based)
• Voting Models
• Auditing & Changelog
• Custom Controllers
• External Signing (DocuSign/DocuSeal)
• Email & SMS Verification
• Ideas & Examples (10)
• Extending Models & Migrations
• Full Testing Guide

How It Works (Data Flow)

Keep approvals close to where changes happen (models) or intercept in controllers. Steps define who can sign and how many signatures you require.

Extending Migrations and Models

• Add columns to the published migrations (e.g., reason, category, workspace_id) with a new migration; the package models use $guarded = [], so new attributes are writable.
• If you need JSON casting or extra relations, create an app model that extends the package model:

Use events like ApprovalRequestCaptured to populate new columns or meta. See Auditing & Changelog.

Search keywords: "laravel approval workflow", "laravel multi signature approvals", "human in the loop approvals", "laravel model guarded changes", "laravel approval steps thresholds", "spatie permissions approval flow", "controller intercept approvals", "two-man rule laravel".

Documentation Website

Guardrails ships build scripts instead of doc sources so the Composer install stays slim. The GitHub Pages deployment uses scripts/docs-site/build-docs-site.js to assemble a Docusaurus bundle from resources/docs on demand.

• Generate a local bundle with node scripts/docs-site/build-docs-site.js ./build/docs-site (requires Node 20+). When previewing locally, open http://localhost:3000/guardrails/ after running npx serve ./build/docs-site. For a root-based preview, run DOCS_BASE_URL=/ node scripts/docs-site/build-docs-site.js ./build/docs-site-local && npx serve ./build/docs-site-local.
• Configure optional environment variables (DOCS_SITE_URL, DOCS_BASE_URL, DOCS_REPOSITORY_URL, DOCS_PACKAGIST_URL) to tune canonical URLs and metadata. Defaults infer the correct GitHub Pages paths from the current repository.
• The published site exposes /playground and /assistant routes for the interactive flow builder and BYO-key AI chat, both running entirely in the browser.
• Tags that start with v automatically generate frozen documentation snapshots so visitors can browse historical releases.
• .github/workflows/docs-site.yml runs on every push and tag, rebuilding the static site and deploying it to GitHub Pages (gh-pages branch).

Tests & Coverage

Run the full suite with Pest (quiet mode by default):

Generate coverage locally when you need instrumentation or Clover output for CI:

See the Full Testing Guide for environment setup, Laravel Testbench tips, and additional testing recipes.

Support

If this package saves you time, please consider:

• Starring the repo: https://github.com/ovac/guardrails
• Sponsoring on GitHub: https://github.com/sponsors/ovac4u