Skip to content

9.0.0

Latest

Choose a tag to compare

@santigarcor santigarcor released this 10 Nov 15:34

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, PermissionRemoved and PermissionSynced in Laratrust\Events. Listen to them like any other Laravel event.
  • Eager-loadable relationships: Role::with('users')->get() works for every model in user_models.
  • Blade: the directives use Blade::if, so @elserole, @unlessrole and the same forms of @permission and @ability work.
  • Query scopes: they use the #[Scope] attribute.
  • Enums: backed enums work as role, permission and team names.

Middleware

  • Multiple guards: guard:web|admin checks the user of the first authenticated guard, like Laravel's auth middleware (#488).
  • Translated messages: the abort and redirect messages go through __() (#650).
  • Helpers: Role::using(), Permission::using() and Ability::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 viewLaratrust gate protects the panel, and by default allows only the local environment.
  • Teams: with teams enabled, roles and permissions are assigned one team at a time.
  • Enforced on the server: create_permissions and not_removable are now checked on save, and the submitted keys are validated.
  • Try it without an app: run composer serve in the repository to open the panel with demo data.

Fixes

  • Ambiguous team column in whereHasRole() and whereHasPermission() (#695).
  • allPermissions($team) and whereHasPermission() now apply the team to the pivot tables.
  • whereDoesntHavePermissions() returns only the users without any permission, direct or through a role.
  • whereHasRole(), whereHasPermission() and Role::hasPermission() split pipe-separated names.
  • addRole() and givePermission() 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) and can('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 $table property.
  • A misconfigured model class throws a clear exception that names the config key.

Removed

  • The query checkers, custom checkers and the checkers config.
  • flushCache(): use flushLaratrustCache().
  • The laratrust:add-trait and laratrust:upgrade commands, and Laratrust\Helper.
  • The string events, laratrustObserve() and the static event listeners.
  • The laratrust-assets publish tag.

Other changes

  • The generated migrations are anonymous classes.
  • laratrust:seeder always writes to database/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