Repository navigation
Laratrust 9.0.0
Laratrust 9 is a new major version for Laravel 13 and PHP 8.3+. Permission checks are much faster, the API is cleaner, a long list of bugs is fixed, and the admin panel is rebuilt.
Important
This release has breaking changes. Read the upgrade guide before you upgrade. Most apps only need the required steps: update composer, republish the config, clear the caches and, if you use the admin panel, define the viewLaratrust gate.
If you can't move to PHP 8.3 and Laravel 13 yet, stay on 8.x, which supports Laravel 10 to 13.
Highlights
Much faster checks (#681, #645)
- A user's roles and permissions now load with at most 4 queries, however many roles they have. 8.x ran one query per role.
- The results are kept for the whole request, queue job or Octane request, even with the cache disabled. Repeated
hasPermission()calls don't query the database again. - Exact permission names are a hash lookup, so users with thousands of direct permissions are checked in microseconds.
- Each role's name and permissions are cached once and shared by its users. When you rename, edit or delete a role, every user sees the change right away.
- Renaming, deleting or restoring a permission, and force deleting a role or a team, now flushes the affected users and roles.
- Customize the cache keys, e.g. per tenant, by overriding
laratrustCacheKey()on your user and role models (#705). Laratrust::reset()forgets the loaded data in long-running processes.
Modern Laravel API
- Event classes:
RoleAdded,RoleRemoved,RoleSynced,PermissionAdded,PermissionRemovedandPermissionSyncedinLaratrust\Events. Listen to them like any other Laravel event. - Eager-loadable relationships:
Role::with('users')->get()works for every model inuser_models. - Blade: the directives use
Blade::if, so@elserole,@unlessroleand the same forms of@permissionand@abilitywork. - Query scopes: they use the
#[Scope]attribute. - Enums: backed enums work as role, permission and team names.
Middleware
- Multiple guards:
guard:web|adminchecks the user of the first authenticated guard, like Laravel'sauthmiddleware (#488). - Translated messages: the abort and redirect messages go through
__()(#650). - Helpers:
Role::using(),Permission::using()andAbility::using()build the middleware strings, e.g.Role::using('admin', team: 'acme', guards: ['web', 'admin']). - Misplaced parameters: a parameter in the wrong place now throws, instead of being ignored silently.
Rebuilt admin panel
- New stack: Tailwind CSS v4 and Alpine.js v3, with dark mode, a mobile menu, filters and select all/none.
- Nothing to publish: the assets are inlined in the pages, with your CSP nonce when you set one.
- Authorization: the
viewLaratrustgate protects the panel, and by default allows only thelocalenvironment. - Teams: with teams enabled, roles and permissions are assigned one team at a time.
- Enforced on the server:
create_permissionsandnot_removableare now checked on save, and the submitted keys are validated. - Try it without an app: run
composer servein the repository to open the panel with demo data.
Fixes
- Ambiguous team column in
whereHasRole()andwhereHasPermission()(#695). allPermissions($team)andwhereHasPermission()now apply the team to the pivot tables.whereDoesntHavePermissions()returns only the users without any permission, direct or through a role.whereHasRole(),whereHasPermission()andRole::hasPermission()split pipe-separated names.addRole()andgivePermission()do nothing when the assignment already exists. In 8.x they could fail on the primary key.- Removing an assignment that doesn't exist does nothing and dispatches no event.
- A team name that doesn't exist matches nothing in checks and scopes, instead of throwing a 404.
- With
permissions_as_gates,can('edit', $post)andcan('create', Post::class)no longer treat the post or the class as the team. - Force deleting a team also removes the direct permissions given within it.
- The role, permission and team models respect a
$tableproperty. - A misconfigured model class throws a clear exception that names the config key.
Removed
- The
querycheckers, custom checkers and thecheckersconfig. flushCache(): useflushLaratrustCache().- The
laratrust:add-traitandlaratrust:upgradecommands, andLaratrust\Helper. - The string events,
laratrustObserve()and the static event listeners. - The
laratrust-assetspublish tag.
Other changes
- The generated migrations are anonymous classes.
laratrust:seederalways writes todatabase/seeders.- The package is checked with PHPStan (level 7), Pint and Rector. The tests run on PHP 8.3–8.5 and on MySQL in CI.
Full list of changes: CHANGELOG.md · Upgrade guide: 8.x → 9.x