Core Laravel Package

Getting Started

Install MoonShine 4.x and scaffold the admin panel:

composer require moonshine/moonshine
php artisan moonshine:install

The installer publishes config/assets, creates the MoonShine application directories (typically under app/MoonShine), and registers the admin routes/provider. After installation:

1. Check config/moonshine.php for route prefix, middleware, auth guard, and branding options.
2. Create an admin user with the package’s user command or a seeder.
3. Visit /admin (or your configured prefix) and log in.

Your first real use case should be a single CRUD resource:

php artisan moonshine:resource Post

Then open the generated resource under app/MoonShine/Resources, define form fields and table columns for the Post model, register the resource in the menu/provider if needed, and reload /admin.

For 4.18.2 specifically: treat it as a patch release in the 4.x line. Use the MoonShine monorepo changelog for commit-level details, and make sure any examples you copy match 4.x docs rather than older 3.x snippets.

Implementation Patterns

Resource-centric CRUD. Most day-to-day work happens in MoonShine resources. A resource maps an Eloquent model to admin screens: index table, create/edit forms, detail view, filters, actions, and authorization. Keep resources thin and push domain logic into services/actions.

Fields and columns. Define form fields in the resource’s fields method and table columns separately. Use relationship fields for BelongsTo, HasMany, and many-to-many editing, and use Laravel validation rules directly on fields where possible.

Menus and navigation. Group resources into logical admin sections. Menu configuration usually lives in the generated MoonShine application structure or dedicated menu classes. Keep labels and icons consistent so the admin panel remains navigable as resources grow.

Authorization. Lean on Laravel policies and gates. MoonShine resources can expose visibility and ability checks; make sure policy methods and resource canSee/view checks agree. For custom pages and actions, add explicit authorization rather than relying on route middleware alone.

Custom pages and dashboards. Use MoonShine page classes for dashboards, settings screens, and reports. Pages can compose fields, cards, charts, and action buttons without creating a full resource.

Actions and bulk actions. Implement workflow buttons as actions: export selected rows, change status, send notifications, etc. Put mutations in a service or job, wrap multi-step writes in transactions, and require confirmation for destructive operations.

Query customization. Use resource query hooks to add eager loading, default ordering, tenant scoping, and soft-delete handling. Prefer with() for relationships displayed in tables to avoid N+1 queries.

Testing and integration. Write feature tests that authenticate an admin user and hit MoonShine routes. Keep factories and policies in the main Laravel app so admin and API behavior share the same domain rules. Avoid putting business logic directly in resource classes; call application services instead.

Gotchas and Tips

• v4 vs v3 differences. Namespaces, directory layout, and APIs changed in MoonShine 4. Do not paste v3 examples into a 4.x project without checking the current docs.
• Clear caches after structural changes. After changing config, menus, providers, or resources, run php artisan optimize:clear. If assets were updated, republish them as directed by the installer/upgrade docs.
• Policy mismatches cause 403s. If a resource appears in the menu but returns 403, check the model policy, resource visibility methods, and auth guard configuration.
• Field names must match model attributes. Relationship columns need correct dot notation and eager loading. A missing with() is a common cause of slow admin tables.
• Validation belongs in fields or form requests. Simple rules can live on fields; complex cross-field validation should move into a form request or dedicated validator so it is testable.
• Custom actions need authorization and confirmation. Do not expose bulk mutations without policy checks, and use database transactions for multi-record changes.
• Debug with Laravel’s tools first. Use php artisan route:list --path=admin, application logs, and the generated app/MoonShine files to trace routing and rendering issues.
• Upgrade deliberately. For patch releases such as 4.18.2, update Composer, run any required publish/migrate commands, clear caches, and smoke-test login, resource index/create/edit, and custom actions. Consult the monorepo changelog for deprecations before larger jumps.
• Extension points. Prefer custom fields, pages, actions, and menu items over forking package internals. Publishable config and assets are the supported way to adjust behavior without patching vendor code.