Craftable Laravel Package

Technical Evaluation

Architecture fit This package sits directly on top of spatie/laravel-permission and exposes that package's Role / Permission contracts as its authorization surface. Its architecture is therefore derivative: most of the meaningful behaviour — role resolution, guard/team scoping, permission caching — is owned upstream, and this package contributes orchestration plus (per the release notes) alignment with dejwcake/admin-auth. The lockstep version alignment with dejwcake/admin-auth 2.1.0 is the single most important architectural fact here: these two packages are co-released and must be treated as a versioned bundle, not independently versioned dependencies. Any integration plan that upgrades one without the other is unsound.

Integration feasibility Low-to-moderate effort. The release notes explicitly state no code changes in this package, so the work is almost entirely:

1. Bumping spatie/laravel-permission from ^7.4 to ^8.3.
2. Updating any first-party Role / Permission contract implementations so findByName() / findOrCreate() accept BackedEnum|string.
3. Regenerating and re-running the authorization test suite.

Apps that use the stock Spatie models and never implement the contracts will likely see a near-mechanical upgrade. Apps with custom models, enum-backed roles, or multi-guard/teams configuration carry the real effort.

Technical risk

Note the risk is asymmetric: this package is well-tested and unchanged, so the risk is not in its diff — it is in everything the diff drags along.

Key questions

• Does the application implement Role / Permission contracts itself, or extend Spatie's models? (Determines whether this is a 1-hour or 1-sprint change.)
• Which other installed packages declare a spatie/laravel-permission constraint, and do any still cap at ^7?
• Are roles referenced by enum anywhere in app code, config, or seeders — i.e. is BackedEnum support already relied upon, or newly available?
• What is Spatie v8's minimum PHP/Laravel matrix, and does it match our runtime?
• Does v8 alter permission cache keys or invalidation? (Affects zero-downtime deploy procedure.)
• Is dejwcake/admin-auth currently pinned at 2.0.x, and is its 2.1.0 upgrade independently safe?
• Do we consume anything from this package's shipped tests or CI config?

Integration Approach

Stack fit Fits a standard Laravel authorization stack with no architectural adaptation required — the package's job is unchanged; only its dependency floor moves. The material fit consideration is fleet fit: if multiple apps share this package, they should be upgraded as a cohort so the Spatie major version doesn't diverge across environments.

Migration path

1. Branch and freeze other dependency upgrades on that branch.
2. composer why-not spatie/laravel-permission ^8.3 to enumerate blockers before touching anything.
3. Bump dejwcake/admin-auth to 2.1.0 and this package to 2.1.0 in the same commit, then resolve Spatie to ^8.3.
4. Update first-party contract implementations: widen findByName() / findOrCreate() signatures to BackedEnum|string (accepting a union is backward compatible; narrowing is not).
5. Read the upstream v7→v8 guide in full and diff it against our config (config/permission.php, guard/team settings, cache store).
6. Run the authorization test suite plus, ideally, a characterization test asserting the resolved role/permission set for a representative user before and after the bump.
7. Clear the permission cache as part of the deploy, not after.

Compatibility Two compatibility axes must be satisfied simultaneously: (a) PHP/Laravel version support in Spatie v8.3, and (b) the transitive constraint graph — every installed package declaring a spatie/laravel-permission requirement must accept ^8.3. Axis (b) is the more likely source of surprise and should be checked first, since a conflict there invalidates the whole plan.

Sequencing

1. Dependency audit and conflict check (blocking gate).
2. Upstream v7→v8 guide review; document any behavioural deltas.
3. Code change: contract signatures only.
4. Full test suite; characterization diff of permission resolution.
5. Staging deploy with a production-like role/permission snapshot; verify cache warm/cold behaviour and a login-through-to-authorized-route smoke test.
6. Production deploy with permission cache cleared; watch authorization errors for 24–48h.

Operational Impact

Maintenance The release is predominantly hygiene: PHPMD 3 with a checked-in phpmd.yml, coverage reporting on the pgsql CI job, MariaDB 12.3 in compose and CI, and AGENTS.md / CLAUDE.md for AI-assisted contribution. That is a positive maintainability signal — static analysis is enforced rather than aspirational, and the DB matrix is current. The countervailing cost is inherited churn: by binding tightly to Spatie's major line, this package converts upstream majors into our maintenance events. Budget for a Spatie-major upgrade roughly annually, and expect the two packages to move together.

Support Because this release contains no code changes, defects here will overwhelmingly be upstream defects. Support routing should point at Spatie's issue tracker first, and the team should be explicit that this package cannot patch around an upstream v8 regression. The dist-archive slimming is a modest support win: fewer files in vendor/ means cleaner dependency audits and less noise in licence/SBOM scans. Keep the upstream v8 upgrade guide linked from the internal runbook — the contract signature change is exactly the kind of thing that gets rediscovered painfully six months later.

Scaling No runtime, query, or caching changes are claimed, so the release should be scaling-neutral. The one thing to confirm rather than assume is that v8.3 does not change permission cache structure or invalidation — permission caching is the load-bearing element in any high-traffic authorization path, and a silent change there would show up as either stale authorizations or a database hit on every check. Validate under realistic concurrency in staging, not just functionally.

Failure modes

• Fatal type error in custom Role/Permission implementations that weren't widened — surfaces at role lookup, i.e. on authenticated requests, which means a broad blast radius.
• Composer resolution failure from a third-party package still capping Spatie at ^7 — fails loudly at build time; low severity, high annoyance.
• Half-upgraded pair — this package at 2.1.0 with admin-auth at 2.0.x, or vice versa. Avoid by upgrading atomically.
• Stale permission cache after deploy producing "authorized yesterday, forbidden today" reports.
• Inherited behavioural change from Spatie v8 not covered by existing tests — mitigated only by the characterization-diff step above.

Ramp-up For a team consuming the package with stock models: minimal — a few hours, mostly dependency resolution and test verification. For a team with custom contract implementations or a broad multi-package authorization surface: plan a day or two including staging validation, and assign someone who already understands the role/permission model rather than treating this as a routine version bump. The release notes are unusually clear about the one real code-level requirement (the BackedEnum|string signature), which meaningfully shortens discovery time — use them as the checklist.

Recommendation: Adopt 2.1.0, upgrading in lockstep with dejwcake/admin-auth 2.1.0, gated on the dependency-conflict audit and on confirming no first-party contract implementations remain on the old signatures. Treat the Spatie v8 move as the actual work item; this package's own change surface is effectively zero.