Moonshine Roles Permissions Laravel Package

Getting Started

Version 4.0.0 is a single-purpose release: MoonShine v4 support. There are no new end-user features beyond the compatibility bump, so treat this as a lockstep upgrade of moonshine/moonshine + sweet1s/moonshine-roles-permissions, not an optional minor update.

1. Check constraints before anything else. Open the package's composer.json on the 4.0.0 tag and confirm the moonshine/moonshine (^4.0), spatie/laravel-permission, PHP, and Laravel version ranges against your app. The whole upgrade hinges on whether your app can move to MoonShine 4.
2. Upgrade in one commit: bump moonshine/moonshine to ^4.0 and this package to ^4.0 together, then composer update moonshine/moonshine sweet1s/moonshine-roles-permissions --with-dependencies.
3. Re-publish and diff. php artisan vendor:publish --provider="SWEET1S\MoonshineRolesPermissions\...ServiceProvider" --force into a scratch directory and diff the config/views/migrations against what you have. Do not blindly --force over customised views.
4. Migrate: php artisan migrate, then php artisan permission:cache-reset and php artisan optimize:clear.
5. Verify the user model still wires up the package trait alongside Spatie's HasRoles, and that guard_name on roles/permissions matches the guard MoonShine authenticates with.
6. Where to look first: config/moonshine-roles-permissions.php (resource registration + guard), the package's src/Resources and src/Traits directories for the current class names, and the MoonShine 4 upgrade guide for whatever broke in your own admin code.
7. First use case: log in as a super-admin, open the Roles resource, create a role with two or three permissions, assign it to a test user, then confirm a permission-gated MoonShine resource disappears from the menu for that user.

Implementation Patterns

• Extend, don't edit. Subclass the package's Role/Permission resources in app/MoonShine/Resources and register your subclasses, so MoonShine 4 API drift never forces you into vendor patches. This matters more now than at 3.x, because every MoonShine major will require a coordinated upgrade.
• Single source of truth for permission names. Define them as an enum or a config/permissions.php array, seed from it, and have a sync command that reconciles DB rows against code. Package UIs drift fast when permissions are typed in by hand.
• Guard MoonShine surfaces with permissions, not just policies. Apply the package's permission check in resource canAccess() and in menu/section visibility so the nav matches reality — a resource that 403s but still appears in the sidebar is a support ticket generator.
• Prefer Gate::before for super-admin bypass rather than sprinkling if ($user->hasRole('admin')) through resources, and keep that bypass out of the test environment so your permission tests actually assert something.
• Multi-guard discipline. If your admin users are on a separate guard, the role/permission guard_name must be that guard and the package config must point at the same one. Test it explicitly with a non-default guard user.
• Upgrade playbook for consumers: write a throwaway branch upgrade PR first, run the MoonShine 4 guide checklist against app/MoonShine, then merge. Keep your overridden views minimal so the diff stays small.
• Testing: seed roles/permissions in a base TestCase, use actingAs($admin) plus assertTrue($admin->can('...')), and add one smoke test per gated resource asserting visible/hidden for role and non-role users.

Gotchas and Tips

• Hard break, no dual support. 4.0.0 targets MoonShine v4 only. There is no compatibility shim for 3.x — if you cannot move to MoonShine 4 today, stay pinned to ^3.1 and pin MoonShine accordingly with -W.
• MoonShine 4 itself changed resource/field/component APIs. Overrides of the package's resources, custom fields, or published views from 3.x will likely fail to load or silently render wrong. Diff before you trust it.
• The package cache is not Spatie's cache. After seeding or editing roles, run php artisan permission:cache-reset. Stale cache after a deploy is the most common "permissions don't work" report.
• guard_name mismatch produces permissions that exist but never match — check the roles/permissions tables' guard_name column against config/auth.php and the MoonShine guard.
• Config cache in production: after publishing or editing package config, php artisan config:clear (or re-run config:cache) — otherwise your new config is invisible.
• Provider order: register the package service provider before your own MoonShine admin provider if your resources extend the package's, otherwise class resolution can fail.
• Release notes are thin. 4.0.0 documents only the MoonShine v4 PR — no migration guide, no changelog detail. Read the actual diff (3.1.0...4.0.0) and the composer.json constraints before upgrading; and check the issue tracker for post-release breakage.
• Verify team-scoped permissions (Spatie teams) still work if you rely on them; this release doesn't claim to address them.
• Pin versions in CI to ^4.0 and add a smoke test that boots MoonShine, so a future MoonShine 4.x minor that breaks the package surfaces in your pipeline rather than in production.