Craftable Laravel Package

Product Decisions This Supports

• Upgrade sequencing for RBAC-dependent surfaces. 2.1.0 is a dependency-gated release: this package's own code is unchanged, but it now requires spatie/laravel-permission ^8.3 and aligns with dejwcake/admin-auth 2.1.0. That makes it the control point for a coordinated upgrade of the whole roles/permissions stack — you cannot adopt it on a per-package basis without dragging admin-auth and the underlying permission library along.
• Build vs. buy for admin auth/RBAC. The package continues to track a mainstream upstream (spatie/laravel-permission) rather than forking authorization primitives, which is the right signal if you are deciding between maintaining in-house role management and adopting this plus its companion. Cost of ownership is concentrated in upstream upgrade cadence, not in bespoke code — that is a favourable buying signal.
• Roadmap scoping for the admin panel. Because this release is a pure dependency realignment with zero feature delta, it does not unlock new product capability and should not be sold internally as such. Plan it as maintenance capacity, not as a feature slot. Any roadmap item that depends on enum-typed role/permission lookups (e.g. typed role enums in domain code, policy checks keyed off BackedEnum) becomes possible only after this upgrade lands — worth sequencing that work behind it rather than alongside it.
• Contract-compatibility triage. If product code implements the Role / Permission contracts itself (custom role models, tenancy variants, cached role resolution), findByName() / findOrCreate() must widen to BackedEnum|string. This is the single largest hidden cost and needs an explicit audit ticket before you commit a date to stakeholders.
• Supply-chain hygiene as a standing decision. Dev files (tests, CI and QA configs) no longer ship in dist archives. This is a small but real reduction in installed footprint and in the attack surface of production images — useful when justifying the upgrade to security or platform reviewers, and a reason to prefer dist installs over VCS installs.
• Tooling baseline to adopt as team norm. PHPMD 3 with a committed phpmd.yml, coverage reported on the pgsql CI job, documented baseline regeneration, MariaDB 12.3 across docker-compose and CI, and AGENTS.md / CLAUDE.md. If you are standardising quality gates or AI-assisted contribution conventions across your PHP estate, this package is a reasonable reference implementation to point other teams at.

When to Consider This Package

Adopt (or upgrade to) 2.1.0 when all of the following hold:

• You already run spatie/laravel-permission and are willing to move to ^8.3, or you can schedule that move in the same window. Pinning ^7 makes 2.1.0 uninstallable — this is a hard constraint, not a soft preference.
• You use (or are adopting) dejwcake/admin-auth 2.1.0. The explicit version alignment between the two packages is the strongest argument for taking both together; splitting them invites a resolution conflict and a confusing failure at composer update time.
• You have, or can quickly produce, an inventory of any in-app implementations of the Role / Permission contracts. If that inventory is unknown, the estimate is not credible.
• Your release cadence tolerates a maintenance-only change with no user-visible behaviour — i.e. you are not trying to buy a feature with this deploy.

Look elsewhere or defer when:

• You are mid-freeze, mid-audit, or otherwise cannot touch the permission library. Staying on the previous line is viable precisely because this package ships no code changes; there is no functional regression risk in waiting, only a growing version gap.
• You maintain a vendored or heavily forked spatie/laravel-permission. The contract-signature change multiplies against your own patches and the upgrade becomes an unbounded piece of work.
• Your authorization needs are trivial (a single is_admin flag, no role/permission matrix). A full RBAC package plus its companion is overkill; the upgrade tax recurs with every upstream major.
• You rely on VCS/--prefer-source installs and depend on dev files being present in the installed package (custom test harnesses, contract tests run against vendor). The .gitattributes change removes them from dist archives — verify your pipeline does not assume they exist.

Assessment of the release itself: low functional risk, moderate operational risk. The package authors did the right thing by shipping a dependency-only minor version rather than smuggling behaviour changes into a major upgrade window, and by aligning versions with the companion package. The residual risk sits entirely in the transitive spatie v7→v8 migration and in any local contract implementations.

How to Pitch It (Stakeholders)

To executives — one paragraph: This is a housekeeping release. The package itself is unchanged; it now requires the next major version of the permissions library it sits on, and it lines up with the matching version of our admin-authentication package. There is no new user-facing capability here, and we should not present it as a feature. The reason to do it now is that staying on the old permissions version becomes progressively more expensive the longer we wait, and doing it while the change is still small is materially cheaper than doing it later alongside other work. Cost is a short, bounded engineering task — mainly verifying that any custom role handling in our own code is updated to the new signature — plus a normal regression pass. Recommend scheduling it into the next maintenance window rather than a feature sprint.

To engineering — the practical brief:

• Treat this as a two-package upgrade: spatie/laravel-permission to ^8.3 and dejwcake/admin-auth to 2.1.0, land them in one PR. Do not attempt a partial move.
• First task is a grep-and-review audit for local implementations of the Role / Permission contracts. Widen findByName() and findOrCreate() to BackedEnum|string. This is the only code change we expect to write, and it is the item that sets the schedule.
• Verify install mode. If any environment pulls from source or expects vendor/ to contain package tests and CI configs, the new .gitattributes exclusions will surface as missing files. Prefer dist installs.
• Add a regression check for role/permission resolution on the pgsql job so the contract widening is actually exercised, not just compiled.
• Non-blocking but worth copying: their PHPMD 3 config, coverage reporting on the pgsql CI job, and AGENTS.md / CLAUDE.md. Low effort, decent signal if we are standardising this across packages.
• Rollback story is clean: revert the version pins together. There is no data migration and no schema change in this release, so the blast radius is contained to the deploy.