Exceptions

composer require langsys/laravel-access-guard Copy

PHP 8.2+ Laravel 10 / 11 / 12

Packagist ↗ GitHub ↗ Also: API Keys

A denied authorize() throws Langsys\AccessGuard\Exceptions\UnauthorizedException, which extends Laravel’s AuthorizationException (so it still renders as a 403 and existing handlers keep working). It carries the context that was denied:

use Langsys\AccessGuard\Exceptions\UnauthorizedException;

try {
    AccessGuard::authorize('edit_projects', $project);
} catch (UnauthorizedException $e) {
    $e->permission; // 'edit_projects'
    $e->entity;     // $project
}

The permission name is omitted from the exception message by default so you don’t leak your permission vocabulary in production responses; set display_permission_in_exception => true to include it (handy in local dev). Looking up a role that doesn’t exist throws RoleDoesNotExist.

Caution

If your app routes exceptions to handlers by exact class (a renderer map, a handler-per-basename factory) rather than by instanceof, register Langsys\AccessGuard\Exceptions\UnauthorizedException there — otherwise denials fall through to your generic handler and render as 500s even though authorization itself is working correctly.