Warden

Roles & permissions for Laravel
Instance-level grants, explicit forbids, ownership, multi-tenancy, and ABAC.
Authorization that explains itself.

📖 Table of Contents

• ✨ Features
• 📋 Requirements
• 🚀 Installation
• ⚡ Quick Start
• 🔐 Checking Permissions
• 🎁 Granting & Forbidding
• ⏳ Temporary Access
• 🏠 Ownership
• 🎯 Scoped Roles
• 🏢 Multi-tenancy
• 🔧 Conditional Permissions (ABAC)
• 📊 Querying by Permission
• 🔍 Debugging with explain()
• 📡 Events
• ⚠️ Exceptions
• 🔢 Enums
• 💾 Caching
• 🧪 Testing
• 🛡️ Middleware & Blade
• 🏗️ Schema & Models
• ⚙️ Configuration
• 📖 Recipes
• 🔄 Migrating from silber/bouncer
• 🧪 Development
• 👤 Credits & License

✨ Features

📋 Requirements

🚀 Installation

warden:install publishes the config, the migration, and runs it. You can also publish individually:

Then add the concern to your authority model(s):

🔄 Coming from silber/bouncer? This package conflicts with it by design (same default tables). Run php artisan warden:upgrade to migrate the schema in place. See MIGRATING-FROM-BOUNCER.md.

⬆️ Already on warden 1.x? 2.0 adds a column and a unique index to permissions. Publish and run the upgrade migration — vendor:publish --tag=warden-migrations-v2 then migrate — before the first write. See UPGRADE.md.

⚡ Quick Start

🔐 Checking Permissions

Nothing to learn — it's Laravel's Gate.

Grant vs Check Matrix

📌 Rules:

• forbid() beats every Warden grant.
• By default, Warden answers after your policies — policies always win.
• Set warden.gate.run_before_policies to make forbids veto everything.
• Checks with more than one argument are left to your policies.
• Guests and non-model arguments are never answered by Warden.
• Warden::can() inside a policy recurses through the Gate. Ask the resolver directly — app(Contracts\Resolver::class) — when a policy needs Warden's own answer.
• With warden.gate.register off, Warden abstains from every Gate answer, so a loose permission with no policy behind it reads as denied by every route through the Gate — $user->can(), Warden::can(), cannot(), canAny(), authorize() and the warden.permission middleware all go through the same Gate. What keeps answering is the resolver, app(Contracts\Resolver::class) — and your policies, wherever you have one.

🎁 Granting & Forbidding

📌 Assignments are one hop unless you turn nesting on. assign('auditor')->to($role) writes an edge between roles. By default holders of the outer role gain nothing from it — set warden.roles.nested to true and they inherit the inner role's grants, to warden.roles.max_depth levels deep.

Off by default on purpose, because turning it on widens what every existing assignment reaches. The switch is read on every check rather than baked into a cached payload, so turning it back off takes effect immediately — it is meant to work as an emergency lever. A cycle stops expanding at the depth ceiling instead of throwing.

can(), is() and whereIs() all nest together: a split would let can('publish') say yes while Warden::is($user)->an('editor') says no, painting a menu wrong for precisely the users with the most access.

Best Practices

✅ Do — use forbid() for exceptions:

❌ Don't — model exceptions with scattered conditionals; a forbid() row is queryable, auditable, and revocable:

⏳ Temporary Access

Grants and role assignments can carry an end date. Past it they stop authorizing, stop appearing in whereCan(), and stop being listed by getPermissions() — no command has to run for that to happen.

📌 The date lives on the assignment, not on the role. A role is a shared definition, so an end date there would end it for everyone. On the assignment, the same role can end on different days for different holders — and when it does, the permissions that role lent go with it.

📌 until() goes before to(), like on(): writes execute immediately, so calling it afterwards throws rather than quietly doing nothing. Moving a date counts as a write — it invalidates the cache and fires the same event as any other.

⚠️ A forbid() cannot expire, and until() on one throws. A prohibition that lapsed by clock would turn a forbid beats every grant into until Tuesday, with the grant beneath it still live. Lift it deliberately with unforbid().

📌 A grant reached through a role outlives neither: the earlier of the two dates ends it.

📌 The boundary is exclusive. A row stops counting at the instant it names, not a tick later.

php artisan warden:clean --expired deletes rows past their date. It is hygiene, not part of the mechanism: an expired grant stops authorizing whether or not anyone runs it.

🏠 Ownership

Configure ownership resolution

📌 ownedVia() only registers; it never removes. ownedVia(Post::class, null) sets the global attribute to "App\Models\Post", which is never what you meant. Use notOwned() to take one class out, or 'default_attribute' => null in the config to turn the fallback off everywhere.

📌 A toOwn() grant against a class that resolves no ownership can never grant. The row is written and looks healthy; warden logs a warning so it is greppable.

Best Practices

✅ Do — let ownership carry the common case, forbid the exceptions:

❌ Don't — reimplement ownership inside policies you'll have to keep in sync.

🎯 Scoped Roles

Restrict a role to any model — no global team_id required.

Configure membership resolution

📌 A restricted role's grants apply when the checked entity belongs to the context. Checks without an instance fail closed. Role membership checks (isAn('editor')) ignore restrictions by design.

Best Practices

✅ Do — model teams with the models you already have:

❌ Don't — fall back to one global role plus scattered if ($user->org_id === …) checks.

🏢 Multi-tenancy

Behavior with no active tenant

Configure warden.scope.null_behavior:

• 'all' — sees everything (global + all tenants)
• 'strict' — sees only global rows

📌 Writes always target one exact scope. A write under tenant 5 only affects tenant-5 rows. Global rules are only writable globally.

Reads and deletes are therefore asymmetric: a check under tenant 5 answers global or tenant 5, while retract() and disallow() delete tenant-5 rows only. So a retract under a tenant can succeed and leave the authority still holding the role globally. retract()->from() exposes retractedCount() for callers that need to tell the cases apart:

⚠️ The scope rule is warden's, not Eloquent's. TenantScope filters reads and stamps creates; it does not isolate writes. $permission->delete() and $role->delete() reach rows in every tenant, and the foreign keys cascade below Eloquent entirely. Remove rows through warden's own verbs, or through warden:clean.

⚠️ Pivot tenancy is a plain predicate, not a registered scope, so withoutGlobalScopes() does not lift it. Widen deliberately with Warden::tenant()->removeOnce(...), which is the supported escape hatch.

Under null_behavior => 'strict' it narrows instead. With no active tenant, strict reads only global rows, so removeOnce() turns (scope is null or scope = $tenant) into scope is null — strictly fewer rows than the read it was meant to widen. Under the default 'all' it widens as described.

📌 Relation writes obey the rule too. detach(), sync(), toggle(), syncWithoutDetaching() and updateExistingPivot() on roles() and permissions() touch only rows at the active write scope, and attach() stamps it. A global row the tenant inherits stays out of reach in both directions: under tenant 5, sync([$role]) adds the tenant-5 row beside the global one instead of adopting it, and sync([]) leaves the global one standing.

⚠️ Scope, yes; restriction, no. A relation write narrows to one scope and stops there: it does not filter restricted_to_*, so $user->roles()->detach($editor) removes the scoped-role assignments along with the plain one. That mirrors Warden::retract('editor')->from($user) without ->on(), which deletes them all the same way — the relation is not narrower than the verb it reflects. To remove one context and leave the others, name it: Warden::retract('editor')->on($org)->from($user).

⚠️ A relation captures its write scope when it is built, not when it writes. $user->roles() resolves the active tenant at construction time, so a relation held in a property across a tenant change still writes to the scope it was born in. Ask for it again after switching tenants, or write through Warden::assign() / retract(), which resolve the scope per call — and which also dispatch the typed events and report retractedCount().

📌 A role is global unless the write mints a tenant one. Under an active tenant, allow('editor') attaches to a global editor if one exists, rather than creating a tenant-scoped twin. Roles are looked up by name and scope; a tenant twin only exists once something writes it.

📌 The permission catalog behaves the same way, and in both halves a row the tenant minted for itself wins the global one it shadows. Under a tenant, allow($user)->to('publish') reuses a global publish row when that is all there is, and picks the tenant's own the moment one exists. Set Warden::tenant()->onlyRelations() to keep the catalog global on purpose.

📌 Tenancy::writeScope() takes forRoleGrant, and it defaults to false. A bare call therefore reports the scope of an authority grant; ask with forRoleGrant: true when the holder is a role, or the answer describes a different write than the one you meant.

Best Practices

✅ Do — remove a global forbid where it lives: outside any tenant:

❌ Don't — expect a tenant-scoped unforbid() to lift a global forbid.

🔧 Conditional Permissions (ABAC)

Grants can carry conditions, written in the grammar your queries already use:

Available operators

📌 Important:

• Precedence is SQL's: AND binds tighter than OR.
• Comparisons are strict — no PHP type juggling.
• A null attribute satisfies no operator at all, != included, and values whose types are not decidably comparable fail closed the same way. A missing attribute is different: under Model::preventAccessingMissingAttributes() it throws rather than failing closed.
• Constrained grants share one catalog row per distinct rule, so editing a permission's options changes the rule for every holder of that shape. Write a new condition instead of editing a shared row.
• A boolean value matches only a column the model casts to bool, and such a column matches only a boolean, so writing either mismatch is refused: where('classified', true) needs 'classified' => 'bool' in the model's $casts. A row stored before 3.0 keeps failing closed in checks and in queries alike — php artisan warden:doctor lists those rows.
• The refusal exists because of what the mismatch does to a forbid(): a condition that can never be true makes the prohibition inert, the grant underneath it stays live, and explain() reports that grant without ever mentioning the forbid — a missing cast read as "allowed".
• A permission with no entity is only ever checked without an instance, so constraining one is refused: the shape that would make it match is the shape that rejects it.
• A constrained grant never matches instance-less checks (can('view'), can('view', Document::class)) — they fail closed.
• to()->where() is two writes, not one. to() lands an unconstrained grant that authorises every instance, and where() re-points it at the constrained twin. Only the second step runs in a transaction; between the two the live row is unconditional, and a throw in where() — an unknown operator, a permission with no entity — leaves it that way. Wrap the whole chain in your own transaction when that window matters.

Best Practices

✅ Do — grant broadly, constrain the sensitive part:

❌ Don't — encode workflow logic as constraints (e.g., "drafts visible on Tuesdays"). Complex rules belong in policies.

📊 Querying by Permission

Checks answer "can X do Y?"; Warden can also answer "over which rows?"

Instance grants, class grants, wildcards, everyone-grants, role grants, forbids, tenancy, ownership, and ABAC constraints all compile into the query.

⚠️ What cannot become SQL fails closed: closure-resolved ownership and restricted-role grants contribute no rows.

⚠️ No Gate, no policies. whereCan() answers from warden's own rows only. A policy that would have granted or denied a row is not consulted, so a query and a check can disagree wherever a policy has the last word.

⚠️ The trait is required. Without it, Post::whereCan($user, 'view') never reaches Warden: Laravel reads it as a dynamic where against a column named can, and you get zero rows or a driver error instead of an answer.

Best Practices

✅ Do — drive index pages straight from authorization:

❌ Don't — post-filter with ->get()->filter(fn ($p) => $user->can('view', $p)) — that's the N+1 this scope exists to delete.

🔍 Debugging with explain()

Which of permission and role are populated depends on the cause:

📌 ConditionsNotMet and NoMatchingGrant are different answers: the first names a row that matched the shape but whose conditions were not satisfied — they failed against the instance, or the check named a class and there was no instance to satisfy them with — while the second means nothing matched at all. Both leave Warden abstaining so your policies decide.

📌 Always answered by the database engine — never from cache — so it diagnoses stale-cache issues too.

📡 Events

Every write dispatches a typed, readonly event with hydrated models (never raw IDs). Disable globally with warden.events_enabled.

$actor defaults to the authenticated user. Queues, console commands and impersonation are cases only your application can answer, so point warden.actor_resolver at a class implementing Contracts\ActorResolver:

Pre-action events (opt-in)

Enable with warden.cancellable_events. A listener returning false aborts the write:

📌 A pre-action event covers the whole call, not one item of it. allow($user)->to(['a', 'b']) announces both names in one event, and a listener returning false aborts both: there is no way to veto one and keep the other. Split the call if you need per-item decisions.

📌 sync() never fires nor honors pre-action events — its declarative diff events tell the whole story.

📌 Deleting a catalog row announces what the cascade was predicted to reach. A foreign key removes a permission's grants inside the engine, where no model event fires, so warden reads the doomed rows before the delete and dispatches one PermissionRevoked — or PermissionUnforbidden — per row afterwards. The read is the announcement: if the foreign key is not enforced, the events describe a deletion that did not happen.

📌 That cascade is blind to the active tenant. The doomed rows are read with withoutGlobalScopes(), on purpose — the delete destroys every tenant's grants regardless of which one is active, so counting only the current tenant would promise a smaller loss than the real one.

⚠️ Exceptions

All typed, all catchable the Laravel way:

📌 UnauthorizedException messages are translatable (shipped in English and Spanish). Displaying the missing permission/role name in the message is opt-in via warden.exceptions.display_*.

🔢 Enums

Every public signature that takes a permission or role name also accepts a string-backed enum:

💾 Caching

Enabled by default. One minimal payload per authority, O(1) automatic invalidation, anti-stampede locking, Octane-safe.

Manual invalidation

Best Practices

✅ Do — write through Warden and let invalidation take care of itself:

❌ Don't — raw database edits (seeders, manual SQL) bypass invalidation. After hand-editing rows, call Warden::refresh() — or better, make the edit through the API.

📌 "Through the API" includes the models. Editing a Grant, an AssignedRole or a catalog row through Eloquent invalidates too — renaming a permission or rewriting its options reaches every cached check, because a permission's own columns are baked into the payload. What still needs Warden::refresh() is a write that fires no model event: the query builder, DB::table(), and a raw statement.

⚠️ The in-memory matcher compares permission names byte-exactly, while a case-insensitive database collation may match Edit to edit. Use exact, consistent names.

🧪 Testing

Fake mode

A scripted rule answers for every authority unless you narrow it. Each verb below narrows the rule scripted just before it, so they chain:

Ownership, conditions and tenancy are decided by the same pieces the database engine uses, and a test suite asserts the fake and the engine answer alike across the shapes a rule can take. Narrowing before scripting a rule throws.

📌 The fake is not looser than the engine. A rule with no entity answers entity-less checks only, a condition abstains where it has no instance to read, and an unscripted check abstains so your app's policies still decide. Where the fake cannot express something, it denies rather than granting.

WithPermissions trait

Artisan commands

📌 warden:doctor exits non-zero when it finds something, so it works as a CI gate. It reads every stored condition back through the rule the write path enforces and reports the ones that would be refused today, with the permission and how many grants and forbids point at it. It changes nothing: adding the missing cast and rewriting the condition mean different things, and only you know which one you meant.

🛡️ Middleware & Blade

Off by default. Enable via config:

Middleware

Blade

🏗️ Schema & Models

Four tables:

📌 Revoking removes the grant, never the catalog row. The row is shared, so pruning it inline would destroy a rule other holders point at. warden:clean is the supported way to reclaim rows nothing points at, and --duplicates collapses rows that identify the same permission.

📌 Both pivot relations mix granted and forbidden rows. $role->permissions() and $permission->roles() return every pivot row, whichever polarity it carries — filter to read one side:

📌 Titles are generated once, on creation, and only when none was given. A rename keeps the old title, and setting title to null on an update leaves it null. Recompute one deliberately with Support\Titles\PermissionTitle::generate() or RoleTitle::generate() — the same calls the hook makes.

📌 Ask before you rewrite a title. PermissionTitle::generations() and RoleTitle::generations() return every title Warden could have written for a name, current first — each generator this package has published is transcribed and frozen. A stored title inside that list was Warden's; one outside it was typed by a person and is not yours to overwrite.

php artisan warden:retitle applies exactly that rule across the catalogue: a title an older Warden generated converges on the current wording, a title someone wrote stays, and a null stays null. Run it with --dry-run first.

Any model can hold roles and permissions:

Swap models via config

📌 Never hardcode package classes in relations. Always resolve via config.

⚙️ Configuration

Everything lives in config/warden.php:

📖 Recipes

Authorize someone other than the current user

Ownership through a pivot table

⚠️ Closure-resolved ownership cannot compile into whereCan().

Default role for new users

💡 There is no "role for everyone" by design. Use Warden::allowEveryone()->to(...) for global grants.

Landlord vs tenant databases

Point warden tables at their own connection with warden.connection. The published migration honors it (Schema::connection(...)), and the migration class is anonymous to avoid collisions.

Replace a role instead of stacking

Long-lived processes (Tinker, Octane, queues)

Writes through the API invalidate caches automatically. Only raw DB edits need Warden::refresh(). Tenant state lives in container-scoped bindings, so Octane requests and queue jobs reset themselves.

🔄 Migrating from silber/bouncer

The fluent API is intentionally compatible. The schema upgrades in place (abilities → permissions, permissions pivot → grants). See MIGRATING-FROM-BOUNCER.md for the full equivalence table.

🧪 Development

No local PHP or Composer needed — everything runs through Docker:

👤 Credits & License

• Original concept & API design: Joseph Silber — this project started as an evolution of his Bouncer and keeps his copyright notice.
• Maintainer: Carlos Mayorga

Licensed under the MIT License.

_{Authorization that explains itself.}