Skip to content
CAI
Software that uses CAICheck a score

spatie/laravel-permission

65.7

Adequate · 13 November 2026

3.3k

lines of production code

PHP

primary language

7

measurements over time

CAI band scale
CAI trend line
CAI lens gauges

What this system is

Features

Add role, permission, and combined role-or-permission middleware with BackedEnum support

The src/Middleware directory now includes three new middleware classes—PermissionMiddleware, RoleMiddleware, and RoleOrPermissionMiddleware—that enforce access control by checking user roles and permissions. These middlewares support Laravel's BackedEnum types for roles and permissions, allowing developers to use enum values directly in route definitions or middleware declarations. Each middleware validates the authenticated user (including Passport client credentials) and throws an UnauthorizedException if the required role or permission is not present, providing a consistent and type-safe way to protect routes.

src/Middleware · high confidence

IDE support for Blade directives and modernized CI configuration

This release adds an \ide.json\ file to provide IDE autocompletion for the package's Blade directives (such as \@role\, \@hasrole\, \@unlessrole\, and their end tags). It also replaces the legacy Travis CI and Scrutinizer configurations with modern tooling, introducing \phpstan.neon.dist\ for static analysis, \pint.json\ for code formatting, and updated GitHub Actions badges in the README. The \.gitattributes\ file is updated to exclude these new configuration files and other development artifacts from package exports.

(repo-wide) · high confidence

Initial release of the permission configuration file

This change introduces the \config/permission.php\ file, establishing the default configuration for the Spatie Laravel Permission package. It defines the Eloquent models for permissions, roles, and teams, sets the default database table names and pivot column keys (including \model\_id\ and \team\_id\), and configures feature toggles for teams, wildcard permissions, Octane resets, and exception display. It also sets the default team resolver class and enables the registration of permission check methods and events by default.

config · high confidence

Introduction of new contract interfaces for permissions, roles, and wildcards

The library now exposes formal PHP interfaces for its core domain objects, allowing developers to type-hint against abstractions rather than concrete implementations. New contracts include \Permission\ and \Role\, which define methods for finding entities by name or ID (supporting both strings and BackedEnums), creating entities if they do not exist, and checking permissions. A \PermissionsTeamResolver\ interface is introduced to support configurable team-based permission scoping, while a \Wildcard\ interface defines the contract for custom wildcard permission verification logic.

src/Contracts · high confidence

New Artisan commands and events for managing roles, permissions, and teams

This release introduces a suite of new Artisan commands to manage permissions and roles directly from the console: \permission:assign-role\ to assign a role to a user, \permission:create-permission\ and \permission:create-role\ to create new entries, \permission:show\ to display a table of roles and permissions per guard, \permission:cache-reset\ to flush the permission cache, and \permission:setup-teams\ to generate the migration required for the teams feature. Additionally, the package now dispatches dedicated events (\PermissionAttachedEvent\, \PermissionDetachedEvent\, \RoleAttachedEvent\, \RoleDetachedEvent\) whenever roles or permissions are attached or detached from a model, allowing applications to react to these changes. The \PermissionLoader\ class has been removed in favor of the new \PermissionRegistrar\ for handling permission registration and caching.

src · high confidence

New HasAssignedModels trait for bulk role assignment to multiple models

The \src/Traits\ location introduces a new \HasAssignedModels\ trait that allows roles to be assigned to, removed from, or synced with multiple models in a single operation. This trait provides \assignToModels\, \removeFromModels\, and \syncModels\ methods, which handle grouping models by their morph class and attaching/detaching them via the underlying \model\_has\_roles\ pivot table. It also includes a new \RefreshesPermissionCache\ trait to automatically clear the permission cache when models are saved or deleted, ensuring consistency across bulk operations.

src/Traits · high confidence

Behavioural changes

New exception classes for guards, teams, and wildcard permissions

The library now includes dedicated exception classes to provide clearer error reporting for specific scenarios. New exceptions handle guard mismatches (\GuardDoesNotMatch\), role and permission existence checks with guard context (\RoleAlreadyExists\, \RoleDoesNotExist\, \PermissionAlreadyExists\, \PermissionDoesNotExist\), and teams configuration issues (\TeamModelNotConfigured\, \TeamsNotEnabled\). Additionally, \UnauthorizedException\ has been enhanced to optionally display the specific roles or permissions required for access, and new exceptions (\WildcardPermissionInvalidArgument\, \WildcardPermissionNotImplementsContract\, \WildcardPermissionNotProperlyFormatted\) support the wildcard permission feature by validating input types and formats.

src/Exceptions · high confidence

Removed legacy migration stub using deprecated Schema::dropTable

The \create\_permission\_tables.php.stub\ migration file has been removed. This stub previously utilized the deprecated \Schema::dropTable\ method in its \down()\ method to reverse migrations for the roles, permissions, and their pivot tables. Its removal indicates a shift away from this legacy migration template, likely to prevent users from generating migrations that rely on outdated or removed Laravel schema builder methods.

resources/migrations · high confidence

The \src/Models\ directory now contains complete Eloquent implementations for \Permission\ and \Role\ (replacing the previous minimal stubs in \src/models\). These models now support guard names, BackedEnum values for names/IDs, and team-based scoping. They provide static factory methods (\findByName\, \findById\, \findOrCreate\) that utilize the permission cache for performance, and define proper many-to-many relationships with users and each other via the \PermissionRegistrar\ configuration.

src/Models · high confidence

Updated database migration stubs to support team-based scoping

The database migration stubs have been updated to support multi-tenancy via teams. The \create\_permission\_tables.php.stub\ now conditionally adds a \team\_foreign\_key\ column to the roles, model\_has\_permissions, and model\_has\_roles tables when the \teams\ config option is enabled, adjusting unique constraints and primary keys accordingly. A new \add\_teams\_fields.php.stub\ migration is provided to add this column and update existing tables for applications upgrading from a non-team setup. Both stubs now use \throw\_if\ for configuration validation and clear the permission cache upon execution.

database · high confidence

Test coverage

Added Pest-based test suite for Role and Permission models; Added comprehensive test suite for role, permission, and team traits; Added integration tests for Blade directives, caching, Octane listeners, and routing; Added test coverage for middleware authorization logic; Added test support infrastructure for role and permission testing; Added tests for permission and team management commands; Migrate test suite from PHPUnit to Pest.

Dependencies

Modernizes package for Laravel 12+ and PHP 8.3+ with updated tooling

This update raises the minimum requirements to PHP 8.3 and Laravel 12 (supporting up to Laravel 13), shifting the package away from older Laravel versions. It replaces the PHPUnit test suite with Pest and uses Laravel Pint for code formatting, while introducing Larastan for static analysis. The dependency structure is also modernized by requiring specific illuminate components (auth, container, contracts, database) and adding spatie/laravel-package-tools for better integration.

(dependencies) · high confidence

Written by cca.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

How this codebase got here

Score

  • CAI 66 → 66 (-0.1)
  • Rubric changed (rubric-2026.10.5 → rubric-2026.11.4) — scores are not directly comparable.

Lenses

  • Code Health 68 → 66 (-2.0)
  • Architecture 96 → 96 (+0.1)
  • Maturity 58 → 59 (+0.7)
  • Readiness 85 → 85 (+0.0)
  • Security 68 → 68 (+0.0)

Resolved (3)

  • Duplicate intent: hasPermissionTo vs checkPermissionTo. The HasPermissions trait exposes both hasPermissionTo and checkPermissionTo with identical signatures and likely identical implementations (checking if a user has a permission). This is redundant naming for the same operation.
  • Naming inconsistency between 'Any/All' and 'AnyDirect/AllDirect'. While distinct in logic (roles vs direct), the naming convention is inconsistent. hasAnyPermission and hasAllPermissions do not explicitly state they include role-derived permissions, whereas hasAnyDirectPermission explicitly states 'Direct'. This forces the user to memorize which methods include role permissions and which do not, rather than having a clear pattern like hasPermissionIncludingRoles vs hasDirectPermission.
  • Return type inconsistency between Contract and Model implementations. The Contract interfaces return self, while the concrete Model classes return their specific type (Permission or Role). While technically valid in PHP, this creates a slight inconsistency in the public API surface where the contract promises a generic self but the implementation is more specific. More importantly, findOrCreate on the Contract returns self but on the Model returns the specific class, which is consistent within each type but inconsistent across the abstraction boundary if one expects the contract to define the exact return shape for fluent chaining.

New (9)

  • Duplicated block (6 lines × 4) (src/PermissionServiceProvider.php)
  • Edited copies of one member (3 members, 24+ corresponding lines) (src/Middleware/PermissionMiddleware.php)
  • Edited copy of a member (11 corresponding lines) (src/Traits/HasPermissions.php)
  • Edited copy of a member (13 corresponding lines) (src/Traits/HasPermissions.php)
  • Edited copy of a member (16 corresponding lines) (src/Traits/HasPermissions.php)
  • Edited copy of a member (22 corresponding lines) (src/Traits/HasPermissions.php)
  • Edited copy of a member (38 corresponding lines) (src/Traits/HasPermissions.php)
  • Edited copy of a member (8 corresponding lines) (src/Models/Permission.php)
  • Edited copy of a member (8 corresponding lines) (src/Models/Permission.php)

Changes since last survey

  • 15 commits — 14 feature/other, 1 fixes

By area

  • (repo) — 4 commits
  • docs/basic-usage — 4 commits
  • (root) — 3 commits
  • docs/advanced-usage — 1 commit
  • src/PermissionServiceProvider.php — 1 commit
  • src/Traits — 1 commit
  • tests/Traits — 1 commit

Notable commits

  • fix: Merge pull request #2982 from AleksandrSpicyn/contrib/fix-disabled-teams-relation
  • change: Cover populated and custom disabled teams relations
  • change: Document global scopes and permission cache isolation (#2985)
  • change: Document route group macro middleware ordering
  • change: Merge pull request #2980 from ziadoz/route-group-macros
  • change: Merge pull request #2981 from ziadoz/route-alias-macros
  • change: Merge remote-tracking branch 'origin/main' into review-2981
  • change: Update CHANGELOG
  • change: Update CHANGELOG
  • change: Update CHANGELOG
  • change: Use a valid pivot for the disabled teams relation
  • change: Verify route aliases through authorization outcomes
  • change: add canAny and canAll route macros
  • change: allow role and permission route macros on route groups
  • change: register group route macros individually

Written by cca.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

Survey your own repository

spatie/laravel-permission was measured the same way every project in this corpus was: the same rubric, at a pinned commit, with the result published in full. Point a surveyor at a repository you know and see whether you agree with it.

About this page

  • The score is its most recent published measurement, taken on 13 November 2026 at a pinned commit. It is not a live figure and does not change until the project is measured again.
  • Measured at commit 799e1aec09997b006fbd5087d61c7b4bfeb8ab30 — the exact code this score is about.
  • Scored under rubric-2026.11.4 — the same rubric and the same method as every other entry in this index.
  • Measured by Canine Code Analyzer (cca.canine.dev) using cca measure-2026.11.64+preprod-569132d3dfbe.