Admin Auth Laravel Package

Technical Evaluation

Evidence basis: Updated from the 2.1.0 release notes only. No composer.json, source review, or upstream spatie changelog was supplied. The material fact in 2.1.0 is not a code change but a disclosed dependency: this package requires spatie/laravel-permission. That invalidates one conclusion in the prior assessment — "no exotic runtime dependencies" — and means the middleware's locale resolution is plausibly coupled to the authorization subsystem (e.g., role- or permission-derived locale). All conclusions remain provisional until the source and version matrix are read.

Architecture fit: The middleware-plus-service-provider shape is unchanged, and 2.1.0 introduces no code changes to this package. However, the architectural surface is larger than previously understood: a hard dependency on spatie/laravel-permission means adopting this package pulls a second service provider, a permission cache, and (typically) its own migrations and config into the host application. Coupling is no longer "low and reversible" in the strict sense — reversing it now means unwinding two packages. The single-responsibility framing still holds for the locale logic; the dependency is the new architectural weight.

Integration feasibility: Still Composer-installable and still small, but 2.1.0 upgrades the classification from routine patch to coordinated dependency upgrade. The constraint moves spatie/laravel-permission from ^7.4 to ^8.3 — a major-version bump of a security-adjacent authorization package. Critically, the release notes state the breaking surface lands in the host application, not in this package: any app that implements the Role or Permission contracts itself must widen findByName() / findOrCreate() to accept BackedEnum|string. The 2.0.4 enum-handling questions remain entirely unanswered by this release; no fix is claimed.

Technical risk: Moderate — up from low-to-moderate. The risk has migrated from locale semantics to dependency graph.

• Forced major upgrade of an authorization package. Upgrading a locale middleware now forces spatie 7→8. That upgrade carries its own migration guide, potential contract signature changes, cache-behavior changes, and possibly raised PHP/Laravel floors that propagate to our application. Blast radius is the permission layer, not the locale layer.
• Undeclared scope of the dependency. Whether spatie/laravel-permission is genuinely used in locale resolution (role→locale mapping) or is an over-broad require is unknown. If the middleware performs a permission/role lookup per request, the prior "no I/O, no cache reads" scaling conclusion is wrong. This is the highest-value thing to verify.
• Enum handling still unspecified (carried forward). No statement on whether a string-backed enum is unwrapped to ->value or an int-backed enum now reaches setLocale() and errors. 2.1.0 does not address it.
• No locale-input validation confirmed. Still unverified whether the user-controlled language value is checked against an allowlist.
• Version-lock trap. ^2.1 pins spatie ^8.3. Teams unable to move to spatie 8 in this cycle must pin below 2.1 and will stop receiving locale fixes — including any future 2.0.4 follow-up on enum handling. Confirm the 2.0.x line remains installable and supported.
• Trivial: the phpmd.xml .gitattributes removal has no runtime effect.

Key questions:

1. Does the middleware actually call into spatie/laravel-permission (role/permission→locale), or is the dependency declared but unused? This determines per-request cost and failure modes.
2. What are the PHP/Laravel floors for spatie/laravel-permission 8.3, and do they exceed our current minimums?
3. Do we implement Role / Permission contracts ourselves anywhere (multi-tenancy, custom models, teams)? If yes, the findByName() / findOrCreate() signature change is a required code change on our side.
4. Does the spatie 7→8 guide require data migrations, cache-key changes, or config republication for our setup?
5. Carried forward: exact post-2.0.4 behavior for string-backed vs. int-backed enums on users.language, and whether a regression test exists.
6. Carried forward: is the resolved locale validated against an allowlist before setLocale()?
7. Carried forward: middleware ordering relative to auth, guest/null handling, Octane locale leakage, and resolution precedence.

Integration Approach

Stack fit: Laravel + PHP + Composer, now with spatie/laravel-permission as a required peer. Two service providers, two config surfaces, and a shared cache dependency. Testbench-based testing still implied; no exotic runtime beyond the permission package.

Migration path: No longer a single composer update. Treat 2.1.0 as a two-stage platform change:

1. Upgrade spatie/laravel-permission to ^8.3 in its own branch, following the upstream guide; run the authorization test suite and any contract implementations.
2. Then bump this package to ^2.1 and re-run the locale assertions.

If the spatie upgrade cannot land this cycle, pin ^2.0 <2.1 deliberately and record the exclusion — do not let Composer resolve silently into a partial state. No migrations or config publishing are introduced by this package itself; the spatie upgrade may introduce both.

Compatibility: The binding constraint is now spatie 8.3's PHP/Laravel floor, not this package's. Determine whether it raises our application's minimum supported PHP or Laravel version — that is a platform decision, not a package decision, and it should be made by whoever owns the runtime baseline. dist archives continue to benefit from .gitattributes trimming (tests/, Docker, QA config excluded); --prefer-source unaffected.

Sequencing:

1. Read composer.json for both packages and record the effective PHP/Laravel floor imposed by spatie 8.3.
2. Audit the codebase for custom Role / Permission contract implementations; if present, plan the BackedEnum|string signature change before upgrading.
3. Upgrade spatie to ^8.3 on a branch; run the full auth test suite, permission cache warm/clear checks, and any multi-tenancy/teams tests.
4. Bump this package to ^2.1; confirm it introduces no code delta (as claimed).
5. Re-run the three locale assertions from the 2.0.4 assessment — string attribute, string-backed enum, null/int — since 2.1.0 does not resolve them.
6. Verify middleware ordering against auth and confirm whether a permission lookup now occurs per request.
7. Staging smoke: two users with different locales and different roles, plus one unauthenticated request, plus one role change to confirm locale doesn't go stale.
8. Production rollout as a single coordinated change with the permission package; roll back as a unit if either layer fails.

Operational Impact

Maintenance: Raised from low to moderate. Dependency cadence is now coupled: a change in the permission package can force a release here, and vice versa. Pin explicitly (^2.1 with awareness that it pins spatie ^8.3) and review both changelogs on every release. The 2.0.4 precedent — behavioral change in a patch release — argues against floating constraints. A 3.0 remains plausible around locale resolution semantics; a spatie 9 will now also force a major here.

Support: Both are community OSS with no vendor SLA, and the dependency chain means an upstream spatie issue becomes our issue indirectly. Mitigating factors: spatie is widely deployed and actively maintained, and the locale middleware core remains small enough to fork or reimplement if the dependency proves over-broad. The AGENTS.md / CLAUDE.md additions still read as a positive maintenance signal.

Scaling: Revised upward from negligible. If the middleware consults roles or permissions per request, the hot path now includes a cache read (and potentially a DB query on cache miss) for every request. That is still cheap under normal caching but is not free, and it makes correctness dependent on the permission cache being warm and current. Confirm whether lookups occur in the middleware, and whether the permission cache is shared/redis-backed or per-process. The Octane concern broadens: verify neither locale nor permission state leaks across requests on long-running workers.

Failure modes:

• Permission cache staleness producing a stale locale. A user's role changes but the cached mapping does not, so the UI stays in the old language until cache invalidation. Silent wrong-language UI again — the hardest class.
• Contract signature mismatch. A host implementation of findByName() / findOrCreate() that is not widened to BackedEnum|string becomes a fatal error at upgrade time, not at deploy time.
• Constraint deadlock. ^2.1 requires spatie ^8.3; if another dependency pins spatie ^7, the resolution fails and can block unrelated security patches. Identify that conflict before committing.
• Silent default-locale fallback when language is null, absent, or non-string. Still likely, still undetectable without logging. Recommend logging the fall-through.
• Unvalidated locale string producing missing translations or a translation-file lookup failure.
• Middleware ordering against auth yielding default locale for authenticated users.
• Int-backed enum type error post-2.0.4, if raw values reach setLocale().
• Octane/queue state leakage across requests for both locale and permission cache.

Ramp-up: Raised modestly. The locale middleware is still minutes to read; the permission package is not. New adopters now need working knowledge of spatie's role/permission model, its cache behavior, and its upgrade path — a materially larger surface than "one middleware that calls setLocale()". The undocumented policy question from the prior assessment still stands and is now more important: capture our locale resolution precedence (user attribute → role-based mapping → session → Accept-Language → app default) in an ADR, alongside the decision about whether we accept a hard dependency on a permission package to obtain per-user locale.