Laravel Roles Laravel Package

Product Decisions This Supports

• Build vs. buy for RBAC/admin. This package bundles the whole roles surface — role/permission/level model with inheritance, route middleware, Blade directives, a GUI for non-technical admins, a JSON API, seeders and an install command. The realistic alternative is a sprint of internal work on top of a code-first permission library plus a hand-built admin UI. v13 widens the gap by shipping three self-contained view sets (Bootstrap 4 default, Bootstrap 5, Tailwind) — the "we'd have to restyle the admin screens to match our design system" objection is now a config value, not a fork.
• Security remediation in the admin plane. Two defects that map directly to risk register items are closed: role/permission names are now escaped in the GUI (a stored-XSS path where anyone who could name a role could run markup in the next administrator's session — i.e. privilege escalation to admin), and the JSON API now actually honours the middleware its config describes. The latter is the bigger one: with the API enabled, the routes hardcoded auth:api, so any authenticated user could enumerate every role, permission and user, and create roles. If you have the API on, treat this as an unauthenticated-privilege-escalation class bug that has been live, not a feature upgrade.
• API exposure policy. ROLES_API_MIDDLEWARE_ENABLED is now a real switch rather than decoration. Decide deliberately whether role/permission/user data is exposed over JSON at all, and to whom; the flag gives you a documented rollback (false restores the old, unsafe behaviour — useful only as a temporary compatibility shim while you fix callers, not as a steady state).
• Client contract decisions. Denials from the role/permission/level middleware now return 403 instead of a 500 with a stack trace. Correct, but it changes what your front end and any consumer sees — error handling, monitoring alerts and tests that assert on 500 need review.
• Environment/deployment standardisation. roles:install --css=… --force, roles:update, roles:switch all run unattended, so framework choice becomes a provisioning parameter in Dockerfiles, CI and config-as-code instead of a manual step. Supports standardising admin UI per environment.
• Platform support decisions. PHP 7.2+, Laravel 5.3–13 is claimed, but the tested matrix is PHP 8.2/8.3/8.4 on Laravel 12 and 13. Laravel 11 has been dropped from testing because every 11.x release carries an advisory with no patch. That's a legitimate decision to keep the package installable on legacy apps, but it tells you where confidence actually sits.
• Operational fixes worth noting for roadmap planning. getPermissions() no longer issues a query per user when the relation is loaded (per-page cost on large user lists), and bulk restore/destroy now run in a transaction and report outcomes rather than silently half-applying. Both are the kind of thing that quietly blocks scaling an admin area past a few hundred users.

When to Consider This Package

Adopt when:

• You need an admin-facing RBAC with a GUI that non-engineers can operate, alongside code-level middleware and Blade directives for developers.
• You need a hierarchical role/level model with inheritance, not just flat roles and permissions.
• You're on Laravel 12 or 13 (the tested targets) and want installation, config publishing and UI theming to be scriptable across environments.
• Your stack is Bootstrap 4/5 or Tailwind, so you can adopt a shipped view set without maintaining a fork.
• You want the documentation burden handled — the rewritten readme plus the docs/ folder (install, config, roles, permissions, levels/inheritance, blade & middleware, GUI, artisan, API, seeding, testing, upgrading) materially lowers onboarding and support cost.

Look elsewhere when:

• You need attribute- or policy-based authorization, multi-tenancy, team/organisation scoping, or audit logging. This is a roles/permissions/levels model; those concerns are yours to build around it.
• You want a code-first library with no admin UI and the largest possible ecosystem — a Spatie-style permission package is the natural comparison; this package's differentiator is the GUI plus level hierarchy.
• You're pinned to Laravel 11 and can't move. It's still declared supported and the GUI reportedly works there, but you're off the tested path and on a framework line with an unpatched advisory — factor that into your framework roadmap, not just the package choice.
• You're on PHP 7.2–8.1 and need confidence, not just a declared floor. Only 8.2–8.4 is exercised in CI.
• You need an API that's safe by default out of the box with no configuration review — you must set rolesAPIMiddleware/rolesAPIMiddlewareEnabled deliberately, and the package defaults (role:admin) are a starting point, not a policy.

How to Pitch It (Stakeholders)

For executives (one paragraph): The admin area that governs who can do what in our application had two genuine security defects. When its JSON API was switched on, any logged-in user — not just administrators — could read every role, permission and user record and create new roles, because the routes ignored the middleware settings the package itself ships. Separately, role and permission names were rendered unescaped, so anyone permitted to create a role could plant script that would run inside the next administrator's session. v13.0.0 closes both, hardens the remaining output escaping, and comes back with a clean composer audit. The same release adds Bootstrap 5 and Tailwind admin themes so the screens match our design system, scriptable install/update commands, and a full documentation set. The upgrade is low-effort and requires no data migration.

For engineering leads: Treat this as a security upgrade, not a feature upgrade. Three things to plan for. First, the breaking change: the API route group now builds middleware from config, so audit every consumer of the roles endpoints and confirm rolesAPIMiddleware (default role:admin) is the policy you actually want — ROLES_API_MIDDLEWARE_ENABLED=false is a stopgap only, since it reinstates the insecure behaviour. Second, denials now return 403 rather than a 500 with a stack trace; update client error handling, alerts and any test asserting the old status. Third, Laravel 11 is out of the test matrix — the package still declares support, and the GUI fixes cover 11+, but our own verification should focus on 12/13. Regression scope: API authorization paths, admin GUI rendering under whichever CSS framework we select, and bulk restore/destroy flows, which now run in transactions and report partial failures instead of failing quietly.

For the roadmap conversation: This release removes the blockers to using the package in compliance-adjacent contexts (stored XSS fixed, dependency audit clean, 403 semantics correct) and removes the design-system objection (Bootstrap 5 / Tailwind view sets, default unchanged so existing installs look identical). It also keeps the option open to standardise the admin UI through ROLES_CSS_FRAMEWORK in provisioning rather than maintaining custom views. The residual questions are strategic, not technical: whether we want a roles/permissions JSON API exposed at all, and how long we intend to sit on a framework line the maintainer no longer tests against.