Moonshine Roles Permissions Laravel Package

Technical Evaluation

Architecture fit moonshine-roles-permissions is a Laravel package that layers role/permission management onto the Moonshine admin panel. Architecturally it is a conventional Laravel package: a service provider for registration, publishable config and migrations, and Moonshine resource classes that expose role/permission CRUD in the admin UI. It almost certainly wraps spatie/laravel-permission as the underlying authorization engine rather than implementing its own — that needs confirmation, but it is the dominant pattern for this class of package and determines most of the integration surface.

Fit is conditional and narrow: it is a good fit only for applications already committed to Moonshine as their admin layer. For Laravel apps using Nova, Filament, or custom admin UIs, the package delivers nothing — the value is entirely in the Moonshine resource wiring.

Integration feasibility Straightforward on a greenfield Moonshine v4 project: composer require, publish assets, run migrations, seed the initial super-admin role. The friction is concentrated in version alignment. Release 4.0.0 is a major bump whose only documented change is "added support for Moonshine v4" — this is lockstep versioning, meaning the package's major version tracks the upstream Moonshine major version. That is a reasonable convention but it means the package cannot be evaluated independently of the host application's Moonshine version.

Technical risk

• Single-maintainer / small-org dependency. The release is authored by one contributor under a small GitHub org. Bus factor is the headline risk for anything sitting in the authorization path of an admin panel.
• Lockstep coupling to Moonshine. Every Moonshine major release forces a package major release; a lag in the package blocks the host app's upgrade. Conversely, 4.0.0 gives no indication of whether 3.x receives security fixes.
• Opaque changelog. The 4.0.0 notes contain a single line and no migration guide. "Support for v4" may or may not include breaking changes to published config, resource class names, or permission naming conventions. This is unverified, not confirmed-safe.
• Localization signal. Changelog is written in Russian, which suggests documentation and issue triage may be primarily non-English — relevant to support expectations, not to code quality.

Key questions

1. What are the exact composer.json constraints — does 4.0.0 require Moonshine ^4.0 only, or does it support v3 and v4 simultaneously?
2. Is spatie/laravel-permission a hard dependency, and which major version? A mismatch here causes silent permission-check failures.
3. Are there breaking changes to the published config, migration files, or resource/permission naming between 3.0.0 and 4.0.0?
4. Is there CI and a test suite, and does it run against multiple Laravel/PHP versions?
5. What is the upgrade path for an existing 3.x deployment with live role data — additive migrations or destructive?
6. Who is the maintenance entity behind SWEET1S, and is there any commitment to patching 3.x?

Integration Approach

Stack fit Target stack is PHP 8.1+, a currently supported Laravel major, Moonshine 4.x, and spatie/laravel-permission. The package is only viable where Moonshine is the admin layer; treat that as a hard prerequisite rather than an assumption to revisit later.

Migration path Two distinct paths depending on starting state:

• New Moonshine v4 project: adopt 4.0.0 directly. Lowest risk — no existing role data, no upgrade semantics to reconcile.
• Existing Moonshine v3 project on package 3.0.0: this is a coordinated dual upgrade. Sequence as Moonshine v3 → Moonshine v4 → package 4.0.0, or verify the package's constraints permit a single atomic composer bump. Do not attempt the package upgrade ahead of Moonshine. Capture a database snapshot of roles, permissions, model_has_roles, and model_has_permissions before running any migration, and diff row counts and pivot contents afterward.

Compatibility Because 4.0.0 carries no published compatibility matrix, derive it empirically: read composer.json constraints for moonshine/*, laravel/framework, spatie/laravel-permission, and PHP, then validate in a throwaway branch. Treat any published config file as a diff target — compare the vendor default against the app's published copy before upgrading.

Sequencing

1. Spike branch: install 4.0.0 against a copy of the app, run migrations, confirm admin login and role assignment work end to end.
2. Diff published config and migrations against the app's current copies; reconcile deliberately rather than republishing over them.
3. Verify authorization gates on a representative sample of Moonshine resources — read, write, and delete — for at least two distinct roles.
4. Confirm permission cache invalidation behaves (see below).
5. Merge behind the normal release process; keep the 3.0.0 lock available for rollback.

Do not bundle this with unrelated Moonshine resource work — the upgrade needs a clean blast radius.

Operational Impact

Maintenance Ongoing cost is low in code terms but carries a standing upgrade tax: the package must be bumped whenever Moonshine ships a major release, and the team absorbs that coordination work. Ownership should sit with whoever owns the admin panel, with the dependency pinned to an exact minor version rather than a floating constraint — this is not a package to allow ^4.0 drift on, given the absence of a test matrix.

Support Expect self-service. Documentation is likely thin, the changelog is one line and non-English, and upstream issue response is not a schedule you can plan against. Budget for reading the package source when behavior is unclear — it is a small codebase, which makes this tractable, but it is real time.

Scaling The performance profile is inherited from spatie/laravel-permission: permission lookups are cached, so steady-state request cost is negligible. The scaling concern is not throughput but cache correctness — invalidation must fire on every role/permission mutation path, including any seeders, queued jobs, or direct DB writes that bypass the package's UI. Admin-panel scale is inherently low-traffic, so this is a correctness risk, not a capacity risk.

Failure modes

• Version skew: package installed against a mismatched Moonshine major → fatal errors or silently missing admin resources. Highest-probability failure, and the direct consequence of lockstep versioning.
• Stale permission cache: role changes appear not to take effect, users retain revoked access. Verify invalidation explicitly during rollout.
• Schema drift: publishing 4.0.0 migrations over customized 3.x migrations → duplicate columns or failed migrations in production. Always diff before running.
• Orphaned pivot rows: if 4.0.0 alters role/permission naming or table structure without a data migration, assignments may silently detach, effectively granting or revoking access unexpectedly. Audit post-migration.
• Abandonment: no 3.x patch commitment means a stalled 4.x line leaves the admin authorization layer unpatched.

Ramp-up For a Laravel developer already fluent in spatie/laravel-permission, ramp-up is under a day — the concepts transfer directly and only the Moonshine resource wiring is new. For a team without that background, add time for Moonshine's resource/policy conventions specifically. Either way, the practical onboarding artifact is a short internal runbook covering the upgrade sequencing above, since upstream will not provide one.