Eloquent Roles Laravel Package

Technical Evaluation

Architecture fit whilesmart/eloquent-roles is a role/permission package built on Eloquent, targeting the same problem space as Spatie's laravel-permission. Architecturally it should slot in the same layer: model-level trait consumption, polymorphic pivot tables linking users (and other authenticatables) to roles, and policy/middleware/Blade integration for authorization checks. For a TPM the relevant question is whether this is a replacement for an existing authorization layer or an additive one. It is not an identity provider, not a policy engine, and it will not replace Laravel Gates/Policies — it feeds them. That constrains blast radius: adoption is usually reversible at the model layer, but authorization semantics are a security-relevant surface, so "reversible" is not "low risk."

Integration feasibility Mechanically low effort: composer install, publish migrations/config, add a trait to the User model, run migrations. Expected effort in a clean codebase is days, not weeks. The real cost is not installation — it is schema design (single vs multi-role, tenancy scoping, guard awareness), backfill of existing roles, and rewriting every authorization check that currently reads a bespoke column or enum. Any package in this space also implies a migration on a live authorization table, which is a coordinated, low-window change.

Technical risk The dominant risk is maturity, not code quality. Two GitHub stars and zero dependents means effectively no production evidence base. In a TPM's risk register:

• Bus factor 1. Single maintainer, no visible ecosystem pressure to keep it current.
• Unvalidated security surface. Authorization bugs are silent and consequential; a small package has not been adversarially tested the way Spatie's has.
• Semantic drift. Role/permission packages diverge on caching, wildcard permissions, team/tenant scoping, and guard handling. Behavior you assume is standard may not be implemented.
• Abandonment. With 0 dependents, the maintainer has no external pull to fix issues; a Laravel major-version bump could strand you.
• Release date caveat. The 2026-03-06 release date is recent but is one data point; it does not establish a maintenance cadence without release history.

Key questions

• What is the release history and commit cadence — is this an active project or a single push?
• Does it support multi-tenancy/team-scoped roles, and multiple guards?
• What is the permission caching model, and is cache invalidation automatic on role change?
• Is there a documented upgrade path across Laravel majors, and a stated support matrix?
• What is the license, and is the maintainer responsive to issues/PRs?
• What is the migration story from our current authorization approach, and is there a data-backfill path?
• Does it integrate with Laravel Gates/Policies, or does it require adopting its own check API everywhere?

Integration Approach

Stack fit Fits natively if the platform is Laravel (or a Laravel-based stack: Livewire, Filament, Inertia, Nova). Zero fit outside PHP/Laravel. Confirm framework version alignment first — a small package is more likely to lag the current Laravel major. If we are on anything other than a supported, current release, that is a stop condition rather than a minor caveat.

Migration path Sequence matters more than tooling here:

1. Inventory every existing authorization decision (columns, enums, hardcoded checks, middleware, policies).
2. Decide the target model — roles only, or roles + granular permissions — before writing migrations. Retrofitting permissions later is the expensive path.
3. Stand up the package's tables alongside the existing mechanism (additive, non-destructive).
4. Dual-write: keep existing checks authoritative, mirror into the new tables, and shadow-compare decisions in logs.
5. Cut over read path module by module, starting with lowest-risk surfaces.
6. Decommission the old column/enum only after a full release cycle of clean shadow comparisons.

There is no vendor-provided migration tooling expected here, so the backfill is our own script either way. That cost exists regardless of which package we pick — it should not be attributed to this library specifically.

Compatibility Verify against: Laravel version, PHP version, database driver (pivot/JSON queries differ across MySQL/Postgres/SQLite), and any existing auth customization. Also confirm coexistence with anything already touching the users table or shipping its own RBAC (admin panels and CMS packages frequently do). Two authorization systems on one model is a defect waiting to happen.

Sequencing Given the adoption signal, do not put this on the critical path of a release. Recommended sequence: timeboxed spike (1–2 days) proving install, migration, one policy check, and cache behavior → side-by-side comparison against Spatie on the same spike → decision gate → if adopted, pilot on one non-critical module → generalize. The comparison step is the important one; the spike's purpose is to produce a defensible build-vs-adopt recommendation, not to prove the package works.

Operational Impact

Maintenance We would be assuming de facto maintenance responsibility. With two stars and no dependents, upstream fixes for our edge cases are unlikely, and a Laravel major upgrade may require us to patch a fork. Budget for a fork-and-maintain contingency, and treat composer.json pinning plus a documented fork procedure as a prerequisite rather than an afterthought. Contrast with Spatie: adopting the less-adopted package trades a small amount of API preference for a materially larger maintenance liability.

Support No commercial support, no meaningful community. Issue response time is unknown and should be measured during the spike (open-issue age, maintainer reply latency). Internally, this means the authorization domain needs a named owner who can read the package source — not just its README — because that source is the documentation for edge cases.

Scaling Two dimensions:

• Data scale: role checks on every request make caching correctness the scaling question. Confirm how permissions are cached and how invalidation is triggered on role/permission mutation; a package that requires manual cache flushing will produce stale-authorization incidents under load.
• Organizational scale: role checks multiply with team size. Without wildcard/inheritance semantics, permission tables and policy code grow linearly with features. Verify expressiveness before committing, since retrofitting hierarchy later is a data migration.

Failure modes

• Silent authorization bypass — a missing or misconfigured check returns permissive. Highest severity; mitigate with explicit deny-by-default tests and a policy coverage check in CI.
• Stale cache after role change — user retains old permissions until flush; mitigate with an invalidation test in the suite.
• Package abandonment / framework incompatibility — blocks upgrades; mitigate with pinned version, fork readiness, and a dependency-review gate.
• Partial migration drift — two authorization sources disagree; mitigate with shadow comparison before cutover.
• Tenant leakage — roles resolved outside tenant scope; mitigate with explicit cross-tenant negative tests if multi-tenancy applies.

Ramp-up Engineer ramp-up on the package API is fast (days). Ramp-up on the authorization model is the real cost and is largely package-independent: the team must agree on role granularity, naming, and the policy layer convention. Plan for a short internal design note and a documented convention before any code, so the package choice does not become the de facto architecture by default.

TPM recommendation Treat as evaluate, do not adopt by default. The 7.07 score reflects a competent-looking package, but opportunity at 29.57 alongside 2 stars and 0 dependents means there is no ecosystem evidence of fitness for production authorization. Authorization is a security-critical, hard-to-reverse surface; the asymmetry favors the established option unless the spike surfaces a specific capability gap that Spatie cannot close cheaply. Fund a 1–2 day spike, require the comparison artifact, and gate adoption on a documented justification plus a named internal owner and fork contingency.