Moonshine Laravel Package

Getting Started

• Verify the package identity first. lee-to/moonshine is the author's source repo; production installs usually target the canonical Composer package (commonly moonshine/moonshine). Check the README and composer show before committing — this repo has 0 known dependents, so confirm you're not pulling a stale mirror or fork.
• Install and scaffold: add the package with Composer, then run the installer (php artisan moonshine:install). This publishes config, migrations, assets, and scaffolds the admin service provider. Run php artisan migrate to create the admin user/guard tables.
• Look here first:
  • app/MoonShine/ — resources, pages, layouts (v3-style structure)
  • config/moonshine.php — route prefix, middleware, guard, auth wiring
  • app/MoonShine/MoonShineServiceProvider.php — resource/page registration
  • app/MoonShine/Layouts/MoonShineLayout.php — menu, branding, notifications
• First use case: scaffold a CRUD admin for one internal model. Run php artisan moonshine:resource Post, open app/MoonShine/Resources/PostResource.php, declare fields(), then visit the panel and log in with the seeded admin. That's the fastest proof of value — a working list/create/edit/delete back office in minutes.

Implementation Patterns

• Resource-centric CRUD. One resource per model. Override fields(), indexFields(), formFields(), detailFields(), filters(), and search(). Keep definitions declarative; push branching into field callbacks or resource methods.
• Fields as the unit of composition. Use built-in fields (Text, Textarea, Select, BelongsTo, HasMany, Image, File, Json) and compose with ->required(), ->rules(), ->hint(). A custom field class is the extension point when a built-in doesn't fit.
• Relations. BelongsTo for foreign keys, HasMany/BelongsToMany for nested editing on detail pages. Always pair relation fields with eager loading to avoid N+1.
• Filters and search. Define reusable filter sets per resource and share them across index and export flows. Searchable columns are opt-in — mark them explicitly.
• Actions. Row actions (edit/delete/custom) and mass actions (bulk delete, export, status change) are the day-to-day workhorse. Implement custom actions as dedicated classes so they're testable and reusable across resources.
• Custom pages and metrics. For dashboards, build pages under app/MoonShine/Pages and compose metric cards/widgets rather than cramming analytics into a resource. Keep them read-only and cache expensive queries.
• Menu and layout. Register resources/pages in MoonShineLayout::menu(). Use this file for branding, nav grouping, and notification badges.
• Authorization. Wire Laravel policies/gates to resources so admins and editors get different scopes. Prefer policy checks over hard-coded role strings.
• Integration tips. Mount the panel on an internal subdomain or behind auth + verified middleware. If you don't want the separate admin user table, point the guard at your existing user model — but update model, guard, and password broker together. For public apps, keep the panel route-prefixed and role/IP-restricted.

Gotchas and Tips

• Version churn is real. Moonshine's API shifted between v2 and v3 (directory layout, provider location, field APIs). Pin an exact version and read the upgrade guide before bumping. With low stars/dependents there are fewer community reports to catch breakage early.
• Asset pipeline. Custom themes may need asset publishing plus a front-end build. If styles break after deploy, assets weren't published or the build wasn't run — republish and run php artisan optimize:clear.
• Field names vs. columns. A field's name is the attribute it reads/writes; typos fail silently or throw at query time. Match field('name') to the model attribute and use ->column() when the display label differs.
• N+1 on index pages. Relation columns and computed fields fire per row. Add ->query(fn ($q) => $q->with([...])) on the resource and verify with Telescope or DB::listen during development.
• Validation lives in two places. Form requests validate your app; fields validate the panel. Duplicate critical rules with ->rules() so the admin UI rejects bad input before it hits the model.
• Auth/guard mismatch. The installer creates its own guard and user table. Repointing it at users requires updating guard config, provider model, and password broker together — otherwise logins fail with no useful error.
• Cache clearing. Menu, layout, and config changes are cached. Run php artisan optimize:clear when new registrations don't show up in the nav.
• Extension points to reach for: custom field classes (render + save + validate), custom action classes, custom pages with your own Blade views, and resource lifecycle hooks (onBeforeSave, onAfterSave) for side effects.
• Debugging: enable Laravel debug and check storage/logs. Most panel issues are route/middleware problems or missing published assets, not field logic. Use php artisan route:list to confirm panel routes registered.
• Treat this as vendor-risk. With zero dependents, keep a thin adapter around resource/field definitions so a swap to another admin panel (Filament, Nova) stays localized if maintenance stalls.