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

Optionally publish the config:

Publish and run the migrations. This one-time publish is required — the package ships the migrations but never loads them, so nothing reaches your schema until you have a copy of your own:

[!IMPORTANT] Set pbac.keys.* in the published config before you run migrate — the migrations read that config at run time and bake the key types into the schema.

🚀 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.

🧰 Console commands

Bootstrapping the first administrator is a data operation, not a migration. Two always-registered commands cover it:

[!IMPORTANT] Scope is never inferred. While pbac.organisation.enabled is on, exactly one of --global / --organisation= is required — a forgotten flag must not silently grant a global role in production. With the feature off, neither flag applies.

Both commands write through the HasRoles trait, so they inherit its strict scope resolution and decision-cache reset; a target model that does not use the trait is rejected rather than written at pivot level. After the change they print the target's resulting role set, which is the verification a bootstrap call needs. An ambiguous --column lookup is refused rather than resolved to the first match.

🔍 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.

⬆️ Upgrading

Migrations are publish-only (breaking)

The service provider no longer calls loadMigrationsFrom(). The migrations reach your application through the pbac-migrations tag only, so schema changes are reviewed in your repository instead of arriving with a composer update.

Publish them once before your next deploy:

Published copies are stamped with the moment you publish them, so they slot into your own migration timeline rather than carrying the package's dates into your repository.

If you already published them from an earlier release, this is a no-op: publishing reuses the filenames you already have, so nothing is duplicated and php artisan migrate finds nothing new.

If you relied on the auto-load and never published, this is a breaking change and needs a hand. Your database already has the pbac tables, but recorded them under the package's own filenames — the published copies carry generated ones, which Laravel reads as unrun. The next migrate would try to create tables that already exist. Reconcile your migrations table with the published filenames before that run.

🤝 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