Download the PHP package langsys/laravel-access-guard without Composer

Laravel Access Guard

Entity-scoped role-based authorization for Laravel. Where spatie/laravel-permission gives users global roles, Access Guard scopes a role to an entity — a user is an admin of this organization and a viewer of that project — and treats API keys as first-class authorizable subjects alongside users.

It authorizes against interfaces you implement on your own models, so it works for any hierarchy (orgs, projects, teams, workspaces, tenants). No hard dependency on any other package; pairs naturally with langsys/laravel-api-keys.

Installation

Migrations are guarded with Schema::hasTable(), so publishing into an app that already has roles / permissions tables is a safe no-op.

The model

Authorization answers one question: may this subject perform this permission on this entity? A subject is either a user (with a role in the entity) or an API key (linked to the entity). Permissions are plain strings.

Wiring your models

Implement the contracts on your own models — Access Guard never assumes your schema.

Don't have a role-assignment scheme yet? Use the HasRolesInEntities trait (see Assigning roles below) and skip writing userRoleInEntity() by hand.

User (AuthorizableByUser, plus optional Authorizable for super admins):

Entity — mark anything you authorize against with GuardableResource:

API key (optional, AuthorizableByKey) — see the api-keys integration below.

Roles & permissions

The bundled Role and Permission models (UUID keys, value + label) cover the vocabulary; role_has_permissions links them.

Seed these from a seeder; override the models via config('access-guard.models').

How the subject is resolved

On each authorize() call, Access Guard:

1. checks for a super admin (the resolved user implements Authorizable and isSuperAdmin() is true) → allow;
2. otherwise picks the API key if one is present on the request, else the authenticated user;
3. runs the key path (keyHasPermission and keyBelongsToEntity) or the user path (userRoleInEntity → roleHasPermission, and not userHasDisabledEntity).

By default the user comes from Auth::user() and the API key from the api_key request attribute (set by langsys/laravel-api-keys). Override either from a service provider:

Using with laravel-api-keys (zero-config)

Install both packages and it just works — no subclassing, no contract to implement. When a key from langsys/laravel-api-keys authenticates, its middleware puts it on the request and Access Guard adapts it automatically: the key's own permissions are checked, and it is authorized against an entity only if it has been linked to that entity.

Link keys to entities with the AuthorizesWithApiKeys trait:

AccessGuard::authorize('edit_projects', $project) then passes for a key that both holds edit_projects and is linked to $project, and is denied otherwise. Linking is the one explicit step — it's a security boundary — and it lives in the entity_has_api_keys pivot. Without api-keys installed, only the user path runs.

Other key systems: any object implementing AuthorizableByKey is used as-is. Point config('access-guard.api_key.bridge') at a different key class to auto-adapt it, or set it to null to turn the bridge off.

Assigning roles (batteries included)

If you don't already have a membership scheme, add the HasRolesInEntities trait to your subject and implement AuthorizableInEntity. You get entity-scoped assignment backed by the model_has_roles pivot — no custom pivot or userRoleInEntity() to write:

A subject can hold multiple roles in one entity; permission checks union them. Override entityIsDisabled($entity) to exclude a subject from an entity even when a role would grant access (e.g. a user who left a project).

Already have your own pivot (like langsys's organization_has_users.role)? Skip the trait and implement AuthorizableByUser instead — both paths are supported.

Gate & policy integration

With register_gate on (default), Gate checks against a GuardableResource route through Access Guard, so the idiomatic Laravel APIs just work:

A subject whose isSuperAdmin() is true passes every Gate check (super_admin_via_gate). Checks that aren't against a GuardableResource are left untouched for your own gates and policies.

Route middleware

The first argument is the permission; the optional second names the route parameter holding the entity (otherwise the first route-bound GuardableResource is used). Denial throws AuthorizationException (403).

Caching

The role → permission map is cached (config cache.store / expiration_time) and flushed automatically on grant/revoke and any role/permission save or delete. Flush manually with php artisan access-guard:cache-reset.

Artisan commands

Enums

Anywhere a permission or role name is accepted you can pass a string or a backed enum:

Events

Set events_enabled => true to fire RoleAssignedToModel, RoleRemovedFromModel, PermissionAssignedToRole, and PermissionRemovedFromRole — useful for audit logging.

Testing