Download the PHP package webrek/laravel-mongo-permission without Composer

webrek/laravel-mongo-permission

Role and permission management for Laravel — MongoDB native.

API-compatible with spatie/laravel-permission for the methods most people use day to day, but the data model, queries, and cache strategy are designed around MongoDB.

Requirements

CI runs every release against the full PHP × Laravel matrix above, excluding the combinations Laravel itself does not support (Laravel 11 and 12 require PHP 8.2+).

Install

Quick start

Status

v1.0 — ready for production. Covers single + multi-tenant Laravel apps, multi-guard auth, request-scoped + persistent caching, eight lifecycle events, wildcard permissions, route middleware, Blade directives, Gate integration, and a full set of Artisan commands.

Why this vs spatie/laravel-permission?

This package targets Laravel apps whose user model and auth surface live in MongoDB. If your stack is SQL, use spatie/laravel-permission — it is mature, widely adopted, and SQL is what it was built for.

If your stack is MongoDB:

• No pivot tables. Role and permission grants live as embedded subdocuments on the user document. One read per permission check, no joins, no model_has_roles / role_has_permissions ceremony.
• Multi-tenant from day one. Every read and write threads team_id through models, cache keys, and events. Tenant isolation is a config flag (strict_team_isolation), not a third-party concern.
• Events that already know your tenant. RoleAttached, PermissionAttached and their counterparts carry team_id and guard in the payload — your audit listener does not have to re-query.
• Cache shape matches the access pattern. Slug arrays are keyed by (user_id, team_id); catalog by (guard, team_id). Lookups are O(1) against the exact tuple the check uses.
• Wildcards on by default. Segment-based matching with a configurable separator, greedy trailing *, exact interior *.
• MongoDB-native indexes. Compound uniques on (name, guard_name, team_id), multikey on permission_ids for reverse queries. Generated by permission:create-indexes.

The public API mimics Spatie's on purpose so existing knowledge transfers. The internals do not.

Caching

hasPermissionTo and hasRole consult an in-memory + Laravel Cache layer keyed by (user_id, team_id). Mutations through assignRole, removeRole, givePermissionTo, revokePermissionTo, and syncRoles/syncPermissions invalidate the affected keys via package events.

Flush manually if needed:

Configure the cache store and key namespace in config/permission.php under the cache key.

Known limitation: changing the permission catalog of a role (e.g. $role->givePermissionTo(...) / $role->revokePermissionTo(...)) does not automatically invalidate the cached slug arrays of every user holding that role — invalidation is per-user, fired by per-user attach or detach events. Run permission:cache-reset after bulk role-catalog edits, or rebuild the cache user-by-user.

Multi-guard

Every Role and Permission is scoped by guard_name. The same name can exist in multiple guards independently. The guard for an operation resolves in this order:

1. Explicit argument: $user->hasRole('admin', 'api')
2. protected string $guard_name property on the user model
3. auth.defaults.guard
4. config('permission.default_guard')

Mismatched guards on assignRole / givePermissionTo calls with model instances throw GuardDoesNotMatch.

Multi-tenant teams

Set permission.teams = true (default) and either call setPermissionsTeamId('your-team-id') manually or supply a closure in permission.team_resolver:

Assignments made while a team is active are scoped to that team. Reads honor the active team. Setting permission.strict_team_isolation = true disables the "team_id = null is global" fallback.

Expiring grants

Roles and permissions can be granted with an expiry. The grant stays on the user document but stops counting toward checks the moment now() passes the expires_at timestamp — even if the cache was warmed before the expiry.

Expired subdocs are not removed automatically. Run the prune command on a schedule (or ad-hoc) to garbage-collect them and free space on user documents:

A role granted with an expiry propagates that expiry to every permission reached through the role — once the role assignment expires, those permissions stop counting too.

Role hierarchy

Roles can inherit permissions from other roles. A user assigned a role transparently gets every permission attached to that role and to every role in its ancestor chain.

Inheritance is multi-parent: a role can extend several parents at once. Diamonds resolve cleanly — a permission reached through more than one path counts once.

Cycle detection. inheritsFrom throws Webrek\MongoPermission\Exceptions\RoleHierarchyCycle if the new edge would create a loop. RoleHierarchyTooDeep fires when the total chain length would exceed permission.role_hierarchy_max_depth (default 5).

Detaching a parent. $role->stopsInheritingFrom($parent) drops the edge. The package fires RoleParentChanged (with action = 'attached' or 'detached') and flushes the registrar cache so every affected user picks up the change on the next read.

Wildcard permissions

enable_wildcard_permission defaults to true. Patterns use . as the separator (configurable via permission.wildcard_separator). A trailing * is greedy and matches all remaining segments; interior * matches exactly one segment; a sole * matches any non-empty name.

Middleware

Denied requests throw Webrek\MongoPermission\Exceptions\UnauthorizedException (HTTP 403). Register a custom exception handler if you want a different response shape.

Blade directives

Gate integration

The package installs a Gate::before hook so $user->can(), @can, and controller authorize() calls consult hasPermissionTo. Unknown permission names return null from the hook so the rest of the Gate stack (Policies, manually-defined gates) still runs.

Events

The package dispatches eight lifecycle events. Subscribe to them for audit logging, cache extensions, or custom side-effects.

PermissionAttached / PermissionDetached carry the model that received the change — a User instance or a Role instance — so listeners can branch on the case. All *Attached / *Detached events include the active team_id and guard, enabling per-tenant auditing without re-querying.

All event classes live in Webrek\MongoPermission\Events.

Artisan commands

Migrating from spatie/laravel-permission

If you are coming from an existing spatie/laravel-permission deployment, permission:migrate-from-spatie reads the canonical spatie tables out of a SQL connection and writes the equivalent documents into the package's Mongo collections.

The command reads these five spatie tables: permissions, roles, role_has_permissions, model_has_roles, model_has_permissions, plus the SQL users table (override with --sql-user-table=) to match SQL user ids to Mongo user documents.

Matching defaults to email (override with --match-by=). Any SQL user without a corresponding Mongo user is reported but does not break the run. The migration is idempotent: a second run skips roles and permissions that already exist with the same (name, guard, team) tuple.

Configuration

Published to config/permission.php:

Testing locally

The repository includes a docker-compose.yml that boots MongoDB 7 with a healthcheck so the test suite starts as soon as the database is ready. No PHP or Mongo install on the host is required.

For consumer apps, the package ships an assertion trait you can drop into your TestCase to test role and permission state with expressive assertions:

License

MIT