Download the PHP package kirchdev/laravel-pbac without Composer

That's it. Tenant-aware authorization in one line, native Laravel Gate semantics, no manual scope plumbing.

✨ Features

• 🎭 Roles & permissions — plain Eloquent models you can swap out for your own (UUID / ULID / int keys).
• 🏢 Organisation/tenant scoping — first-class, with a pluggable OrganisationResolver. Scopes never bleed across tenants.
• 🚪 Native Gate integration — $user->can(), Gate::allows(), Gate::inspect() all Just Work, with fallback to native Laravel gates.
• ⚡ Per-request decision cache — repeated checks within a request are free. Auto-invalidates on role/permission mutations.
• 🔍 Decision trace — opt-in audit trail of why a check returned what it did. Redacted in production by default.
• 🚀 Octane-aware — optional reset listeners on RequestTerminated, TaskTerminated, TickTerminated. No stale state across requests.
• 🧰 Heavy configuration — model / table / column / key types all overridable. UUID setups supported out of the box.
• 🧪 Library-grade — Pest 4 + Testbench, no host app needed.

📦 Installation

Publish and run the migrations:

Optionally publish the config:

🚀 Quick start

Add the HasRoles trait to whichever model should be authorizable:

Create roles, attach permissions, assign, check:

🏢 Multi-tenant authorization

Enable organisation scoping:

Scope authorization for the current request:

The decision cache resets on scope enter/exit, so checks never bleed across tenants.

Assigning global roles when org scoping is enabled

To prevent silent mis-targeting, role mutations by name refuse to resolve a global role unless the caller signals intent. Pass global: true, or wrap the call in Pbac::withoutOrganisation() and assign by Role instance:

Inside an active organisation scope, $user->assignRole('owner') resolves the org-scoped row only — global rows with the same name are deliberately invisible to mutations without the explicit flag.

Bring your own resolver (e.g. backed by a tenancy package or route binding):

Wire it via pbac.organisation.resolver.

🔍 Decision trace

Wondering why a permission check returned what it did? Turn on tracing:

Gate::inspect() carries the decision's reason code via Response::message():

For the human-readable trace, reach for the last decision through the Pbac facade:

Production redacts trace context arrays by default (step names stay; values are stripped). Opt in to the full trace per request when you need it — e.g. for an admin debug route:

🧹 Cascade behaviour on delete

Foreign keys are deliberately set to ON DELETE CASCADE so the indexes never carry stale grants or assignments. Mark this on your operational checklist:

The host-model side is polymorphic (model_type + model_id), so no FK enforces it. Hook your model's deleting/deleted events or run a periodic prune job if user/team deletions are part of your normal flow. If you need an audit trail of historical grants/assignments, capture it before deletion — once the cascade fires, the rows are gone.

⚙️ Configuration highlights

config/pbac.php is heavily parameterised — see the file for inline docs. Most common knobs:

🔁 Migrating from spatie/laravel-permission

Coming from spatie/laravel-permission? See the dedicated guide for schema, API, and multi-tenancy differences plus a copy-pasteable data-migration script: docs/migration-from-spatie-laravel-permission.md.

🧪 Testing

The test suite runs via Testbench + in-memory SQLite — no host app required.

🤝 Contributing

PRs welcome. Conventional Commits required (enforced via commitlint). Husky runs Pint + Larastan + oxlint + oxfmt on git commit, so you can mostly forget about style.

[!TIP] Run pnpm check:fix (Node tooling) and composer pint:fix (PHP) before pushing — CI will catch what husky missed.

🛣️ Versioning

Semantic Versioning. Release notes in release-please.

📄 License

IT-Dienstleistungen Titus Kirch