Getting Started

Install the package with Composer, then publish/run its migrations and config according to the README. Add the package’s roles/permissions traits to your User model, including HasPermissions where direct permissions are needed.
Look first at the README sections for role definitions, permission/ability strings, condition callbacks, and middleware/Blade integration. Check the package config for cache and model customization options.
First use case: seed an admin role with a stable ability such as posts.publish, assign the role to a user, and check access with Laravel’s authorization flow ($user->can('posts.publish'), middleware, or Blade @can).
v3.1.1 is a patch release. It fixes ability-string handling on roles using HasPermissions and ensures conditions are checked once per authorization check. There are no documented breaking changes, but re-run role/permission tests after upgrading.

Implementation Patterns

Define abilities as stable, namespaced strings such as posts.view, posts.edit, and posts.publish. Seed roles and permissions in dedicated seeders so environments and tests stay consistent.
Prefer role-based assignment for coarse access and direct permissions only for exceptions. Use Laravel policies/Gates for resource-level rules, and keep package roles/permissions for broader capability checks.
Put authorization checks close to the boundary: middleware for routes, form requests/policies for actions, and Blade directives for presentation. Avoid scattering raw role-name checks throughout controllers.
When using conditions, write pure callbacks that depend only on the current user/resource state. v3.1.1 evaluates conditions once per check, so avoid relying on repeated invocation or side effects inside condition logic.
Add feature tests for the role/permission matrix, especially role-defined ability strings and conditional permissions. If a condition has observable behavior, assert it is evaluated once where that matters.
For upgrades, run composer update, then the package migrations if any are published, and the full authorization test suite. Clear any package permission cache during deployment and in test setup if caching is enabled.

The v3.1.1 fix specifically affects ability strings on roles using HasPermissions. Re-test any role that grants permissions by string rather than by permission model/ID.
Conditions are now checked once. If existing code depended on a condition callback running multiple times, refactor it to be idempotent and side-effect free.
Keep ability naming consistent. Typos in strings are silent authorization failures; centralize names in constants or an enum.
Be explicit about super-admin bypasses. If you use Gate::before, test that it does not accidentally bypass package conditions or policy checks.
If the package caches roles/permissions, invalidate that cache after seeding, role assignment changes, and in tests. Stale cache is a common source of “works locally, fails in CI” authorization bugs.
Debug authorization failures by checking the resolved abilities for the user, the role’s granted permissions, and whether a condition callback is returning false. Prefer package/Laravel authorization APIs over ad-hoc role comparisons.