moonshine-resources-v4

name: moonshine-resources-v4 description: Use when working on MoonShine v4 ModelResource, CrudResource, CRUD operations, pages, tables, forms, filters, search, query tags, pagination, events, buttons, import/export, metrics, or response modifiers.

MoonShine v4 -- ModelResource

Overview

ModelResource is the primary building block for admin panel sections backed by Eloquent models. It extends CrudResource and provides full CRUD functionality.

KEY V4 CHANGE: Page-Centric Architecture. In v4, many methods that previously lived on the resource class have moved to dedicated page classes (IndexPage, FormPage, DetailPage). Resources declare pages; pages own their fields, filters, buttons, metrics, validation, and component modifiers.

Creating a Resource

php artisan moonshine:resource Post

This generates a resource class plus three page classes (PostIndexPage, PostFormPage, PostDetailPage).

Core Properties

namespace App\MoonShine\Resources\Post;

use App\Models\Post;
use MoonShine\Laravel\Resources\ModelResource;

/**
 * @extends ModelResource<Post>
 */
class PostResource extends ModelResource
{
    protected string $model = Post::class;
    protected string $title = 'Posts';
    protected array $with = ['category'];          // eager load
    protected string $column = 'id';               // display column for breadcrumbs/relations
    protected ?string $alias = null;               // custom URL alias
}

Page-Centric Architecture (v4 Key Change)

Resources declare their page classes in pages(). Each page owns its fields, filters, metrics, buttons, validation, and component modifiers.

class PostResource extends ModelResource
{
    protected function pages(): array
    {
        return [
            PostIndexPage::class,
            PostFormPage::class,
            PostDetailPage::class,
        ];
    }
}

What Moved from Resource to Pages

Properties Removed from Resource

Use modifyListComponent() on IndexPage instead of these removed resource properties:

• $clickAction, $stickyTable, $stickyButtons, $columnSelection

class PostIndexPage extends IndexPage
{
    protected function modifyListComponent(ComponentContract $component): ComponentContract
    {
        return $component->sticky()->stickyButtons()->columnSelection();
    }
}

Declaring in the System

Resources are auto-registered when using php artisan moonshine:resource. Manual registration in MoonShineServiceProvider:

public function boot(CoreContract $core, ConfiguratorContract $config): void
{
    $core->resources([PostResource::class])->pages([...$config->getPages()]);
}

Autoloading: $core->autoload();

Resource Properties

// Sorting
protected string $sortColumn = 'created_at';
protected string $sortDirection = 'DESC';

// Pagination
protected int $itemsPerPage = 25;
protected bool $simplePaginate = false;
protected bool $cursorPaginate = false;

// Async mode (enabled by default, disable on resource or page)
protected bool $isAsync = false;

// Lazy loading (on IndexPage)
protected bool $isLazy = true;

Modal Windows

protected bool $createInModal = true;
protected bool $editInModal = true;
protected bool $detailInModal = true;

Modal modifiers: modifyCreateModal(), modifyEditModal(), modifyDetailModal(), modifyDeleteModal(), modifyMassDeleteModal(), modifyFiltersOffCanvas().

Redirects

use MoonShine\Support\Enums\PageType;

protected ?PageType $redirectAfterSave = PageType::FORM;

public function getRedirectAfterSave(): string { return '/'; }
public function getRedirectAfterDelete(): string { return $this->getIndexPageUrl(); }

Active Actions

use MoonShine\Support\Enums\Action;
use MoonShine\Support\ListOf;

protected function activeActions(): ListOf
{
    return parent::activeActions()->except(Action::VIEW, Action::MASS_DELETE);
}

Available: Action::CREATE, Action::VIEW, Action::UPDATE, Action::DELETE, Action::MASS_DELETE.

Fields in Resources

In v4, fields are declared on the page classes, not on the resource.

class PostIndexPage extends IndexPage
{
    protected function fields(): iterable
    {
        return [ID::make()->sortable(), Text::make('Title')];
    }
}

class PostFormPage extends FormPage
{
    protected function fields(): iterable
    {
        return [Box::make([ID::make(), Text::make('Title')->required()])];
    }
}

Query Modification

Stays on the resource:

protected function modifyQueryBuilder(Builder $builder): Builder
{
    return $builder->where('active', true);
}

protected function modifyItemQueryBuilder(Builder $builder): Builder
{
    return $builder->withTrashed();
}

Query Tags (New in v4)

Defined on IndexPage. Quick-filter buttons displayed above the table.

class PostIndexPage extends IndexPage
{
    protected function queryTags(): array
    {
        return [
            QueryTag::make('With author', fn(Builder $query) => $query->whereNotNull('author_id'))
                ->icon('users')->default(),
            QueryTag::make('Archived', fn(Builder $query) => $query->where('is_archived', true))
                ->alias('archive'),
        ];
    }
}

See references/filters-search-querytags.md for full details.

Filters & Search

Filters are now on IndexPage:

class PostIndexPage extends IndexPage
{
    protected function filters(): iterable
    {
        return [Text::make('Title', 'title')];
    }
}

Search stays on the resource:

protected function search(): array { return ['id', 'title', 'text']; }

Cache filter state: protected bool $saveQueryState = true;

See references/filters-search-querytags.md for full-text, JSON, relation search, and global search.

Metrics

Defined on IndexPage:

class PostIndexPage extends IndexPage
{
    protected function metrics(): array
    {
        return [
            ValueMetric::make('Articles')->value(fn() => Post::count())->columnSpan(6),
        ];
    }
}

Buttons

In v4, buttons are defined on page classes.

// IndexPage: topLeftButtons/topRightButtons for above-table, buttons() for per-row
class PostIndexPage extends IndexPage
{
    protected function topLeftButtons(): ListOf
    {
        return parent::topLeftButtons()->add(
            ActionButton::make('Refresh', '#')
                ->dispatchEvent(AlpineJs::event(JsEvent::TABLE_UPDATED, $this->getListComponentName()))
        );
    }

    protected function buttons(): ListOf
    {
        return parent::buttons()->prepend(
            ActionButton::make('Link', fn(Model $item) => '/endpoint?id=' . $item->getKey())
        );
    }
}

// FormPage: buttons() for page-level, formButtons() for inside-form
class PostFormPage extends FormPage
{
    protected function formButtons(): ListOf
    {
        return parent::formButtons()->add(
            ActionButton::make('Back', fn() => $this->getIndexPageUrl())->class('btn-lg')
        );
    }
}

See references/events-buttons.md for full button reference.

Import/Export

Requires moonshine/import-export package:

use MoonShine\ImportExport\Contracts\HasImportExportContract;
use MoonShine\ImportExport\Traits\ImportExportConcern;

class PostResource extends ModelResource implements HasImportExportContract
{
    use ImportExportConcern;
    protected function importFields(): iterable { return [ID::make(), Text::make('Title')]; }
    protected function exportFields(): iterable { return [ID::make(), Text::make('Title')]; }
}

See references/events-buttons.md for handler configuration.

Events & Lifecycle

Resource CRUD events (stays on the resource, v4 uses DataWrapperContract):

use MoonShine\Contracts\Core\TypeCasts\DataWrapperContract;

protected function beforeCreating(DataWrapperContract $item): DataWrapperContract { return $item; }
protected function afterCreated(DataWrapperContract $item): DataWrapperContract { return $item; }
protected function beforeUpdating(DataWrapperContract $item): DataWrapperContract { return $item; }
protected function afterUpdated(DataWrapperContract $item): DataWrapperContract { return $item; }
protected function beforeDeleting(DataWrapperContract $item): DataWrapperContract { return $item; }
protected function afterDeleted(DataWrapperContract $item): DataWrapperContract { return $item; }
protected function beforeMassDeleting(array $ids): void {}
protected function afterMassDeleted(array $ids): void {}

Resource lifecycle: onLoad() (resource active), onBoot() (instance created). Page lifecycle: onLoad(), booted().

Response Modifiers

use MoonShine\Crud\JsonResponse;

public function modifySaveResponse(JsonResponse $response): JsonResponse { return $response; }
public function modifyDestroyResponse(JsonResponse $response): JsonResponse { return $response; }
public function modifyMassDeleteResponse(JsonResponse $response): JsonResponse { return $response; }
public function modifyErrorResponse(Response $response, Throwable $exception): Response { return $response; }

CRUD Operation Handlers (New in v4)

Override save/delete/mass-delete logic using attributes:

use MoonShine\Crud\Attributes\SaveHandler;
use MoonShine\Crud\Attributes\DestroyHandler;
use MoonShine\Crud\Attributes\MassDestroyHandler;

#[SaveHandler(PostHandlers::class, 'save')]
#[DestroyHandler(PostHandlers::class, 'destroy')]
#[MassDestroyHandler(PostHandlers::class, 'massDestroy')]
class PostResource extends ModelResource { }

final readonly class PostHandlers
{
    public function save(Post $model, array $data): Post
    {
        $model->fill($data);
        $model->save();
        return $model;
    }
    public function destroy(Post $model): bool { return $model->delete(); }
    public function massDestroy(array $ids): void
    {
        Post::query()->whereKey($ids)->each->delete();
    }
}

Authorization

protected bool $withPolicy = true;

Policy methods: viewAny, view, create, update, delete, massDelete, restore, forceDelete. Generate: php artisan moonshine:policy PostPolicy.

Routes Helper

$resource->getUrl();                        // first page
$resource->getIndexPageUrl();               // index page
$resource->getFormPageUrl();                // create page
$resource->getFormPageUrl(1);               // edit page by ID
$resource->getDetailPageUrl(1);             // detail page by ID
$resource->getAsyncMethodUrl('method');     // async method URL
$resource->getRoute('crud.update', $id);    // CRUD routes
$resource->getActivePage();                 // current active page or null

Cross-References

• For field types and relationship fields, see the moonshine-fields-v4 skill.
• For ActionButton advanced usage, see the moonshine-components-v4 skill.
• For Layout and menu configuration, see the moonshine-appearance-v4 skill.
• For TableBuilder and FormBuilder components, see the moonshine-components-v4 skill.
• Detailed CRUD page customization: references/crud-pages.md
• Filters, search, query tags: references/filters-search-querytags.md
• Events, buttons, import/export, metrics: references/events-buttons.md