Index of every page on this site: llms.txt
All skills
labrodev avatar

/labrodev-viewmodel-resource

@4e3053b
Run it yourself

Use when creating, reviewing, or naming ViewModels (App/Layer/*/ViewModels, e.g. BookingIndexViewModel, BookingShowViewModel) or Resources (App/Layer/*/Resources, e.g. BookingIndexResource) — i.e. whenever data is shaped for an Inertia page, Blade template, or JSON payload, or when deciding which fields a model may expose to the browser.

  • 1 file
  • 9 KB
  • MIT
  • Updated 2 months ago
  • GitHub
Use this Skill: https://skilld.dev/gh/labrodev/laravel-playbook/labrodev-viewmodel-resource

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈93 tokens for metadata: the name and description. ≈2.2k when used: this file.

Description uses 4.6% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈369 characters, or 4.6%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

ViewModels & Resources — the presentation boundary

Part of the Labrodev playbook. The law for this component lives in the always-on labrodev-viewmodel-resource guideline (musts, must-nots); the per-file checklist is rules/viewmodels-resources.md. This skill holds the craft: anatomy, canonical templates, and edge cases.

Together these two classes form the security boundary between the database and the browser:

  • The ViewModel decides which data reaches the page (which models, which relations, which options).
  • The Resource decides what fields of that data are exposed (an explicit allowlist).

Neither may be bypassed. Raw Eloquent models never reach Inertia or JSON output.

Responsibility split (controller vs ViewModel vs Resource)

Concern Owner
Authorize, run the primary IndexQuery, paginate, construct ViewModel, Inertia::render(...) Controller → see the labrodev-controller skill
Collect all remaining page data: auxiliary lists, select options, flags, counts — via Query classes ViewModel (App/Layer/{Layer}/{Domain}/ViewModels)
Shape the props: pagination envelope, resolved Resources ViewModel
Allowlist mapping of a single model to public fields Resource (App/Layer/{Layer}/{Domain}/Resources)
Business rules, mutations, workflows Never here → see the labrodev-action skill

The controller hands the ViewModel the primary subject and nothing else. When the template needs more — a project dropdown, a verified-domain flag, enum options — the ViewModel fetches it itself through Query classes (resolve({Model}Query::class)); a controller accumulating query injections to feed the ViewModel is the anti-pattern this split exists to prevent.

Template — Index ViewModel

Naming pattern: {Model}IndexViewModel in App\Layer\{Layer}\{Domain}\ViewModels. Worked example: Booking domain, Dashboard layer.

<?php

declare(strict_types=1);

namespace App\Layer\Dashboard\Booking\ViewModels;

use App\Layer\Dashboard\Booking\Resources\BookingIndexResource;
use App\Layer\Dashboard\Booking\Resources\ServiceOptionResource;
use Core\Domain\Service\Queries\ServiceQuery;
use Illuminate\Pagination\LengthAwarePaginator;
use Spatie\ViewModels\ViewModel;

final class BookingIndexViewModel extends ViewModel
{
    public function __construct(
        private readonly LengthAwarePaginator $items,
    ) {}

    /**
     * @return array<string, mixed>
     */
    public function toArray(): array
    {
        $resourceCollection = BookingIndexResource::collection(
            $this->items->getCollection()
        )->resolve();

        return [
            'bookings' => [
                'data' => $resourceCollection,
                'current_page' => $this->items->currentPage(),
                'last_page' => $this->items->lastPage(),
                'per_page' => $this->items->perPage(),
                'total' => $this->items->total(),
                'from' => $this->items->firstItem(),
                'to' => $this->items->lastItem(),
                'links' => $this->items->linkCollection()->toArray(),
            ],

            'service_options' => $this->serviceOptions(),
        ];
    }

    /**
     * @return array<int, array<string, mixed>>
     */
    private function serviceOptions(): array
    {
        return ServiceOptionResource::collection(
            resolve(ServiceQuery::class)->active()->get()
        )->resolve();
    }
}

Auxiliary data (here the service dropdown) is collected by the ViewModel through the Core Query class — the controller never grows a ServiceQuery injection for it. Enum select/filter options → see the labrodev-enum skill.

The controller constructs it with named arguments (new BookingIndexViewModel(items: $bookings)) and renders Inertia::render('bookings/index', $viewModel->toArray()) → see the labrodev-controller skill.

Template — Show/Edit ViewModel

Naming pattern: {Model}ShowViewModel (or {Model}EditViewModel for form pages) in the same namespace.

<?php

declare(strict_types=1);

namespace App\Layer\Dashboard\Booking\ViewModels;

use App\Layer\Dashboard\Booking\Resources\BookingShowResource;
use Core\Domain\Booking\Models\Booking;
use Spatie\ViewModels\ViewModel;

final class BookingShowViewModel extends ViewModel
{
    public function __construct(
        private readonly Booking $booking,
    ) {}

    /**
     * @return array<string, mixed>
     */
    public function toArray(): array
    {
        $this->booking->load([
            'customer',
            'bookingItems.service',
        ]);

        return [
            'booking' => (new BookingShowResource($this->booking))->resolve(),
        ];
    }
}

The load() list names the relations this page actually renders (each passing through its own allowlisting Resource). Form metadata — select options, permissions, statuses — is added as further keys, collected by the ViewModel itself through Query classes or EnumMapper (→ see the labrodev-enum skill), exactly like the index ViewModel's service_options.

Template — Resource

Naming pattern: {Model}{Context}Resource in App\Layer\{Layer}\{Domain}\Resources. Worked example: Booking domain, Dashboard layer.

<?php

declare(strict_types=1);

namespace App\Layer\Dashboard\Booking\Resources;

use Core\Domain\Booking\Models\Booking;
use Core\Shared\Exceptions\Models\ObjectMissed;
use Illuminate\Http\Request;
use Illuminate\Http\Resources\Json\JsonResource;

/**
 * JsonResource<Booking>
 */
final class BookingIndexResource extends JsonResource
{
    /**
     * @return array<string, mixed>
     * @throws ObjectMissed
     */
    public function toArray(Request $request): array
    {
        $booking = $this->fetchModel();

        return [
            'uuid' => $booking->uuid,
            'reference' => $booking->reference,
            'status' => $booking->status->value,
            'status_label' => $booking->status->label(),
            'starts_at' => $booking->starts_at?->toDateTimeString(),
            'created_at' => $booking->created_at?->toDateTimeString(),
        ];
    }

    /**
     * @throws ObjectMissed
     */
    private function fetchModel(): Booking
    {
        if (! $this->resource instanceof Booking) {
            throw ObjectMissed::make(Booking::class);
        }

        return $this->resource;
    }
}

Props security — everything serializes into the DOM

Inertia serializes all page props into the data-page attribute of the HTML root element. Every prop is visible to anyone inspecting the page source. Therefore:

  • Never pass raw models, full DB records, or unfiltered collections — every value passes through a Resource or a manually constructed array.
  • Audit eager-loaded relations: if the ViewModel loads $model->load(['relation']), the nested relation must also go through its own allowlisting Resource. Nested relations are the most common leak source.
  • When adding a field to a Resource ask: "Does the frontend render this?" If no — remove it.
  • During development, inspect data-page in the browser. Anything visible there is public; if it should not be, fix the Resource or ViewModel.
  • Defense in depth on the model side ($visible) → see the labrodev-model skill.

Edge cases

  • Blade / classic MVC ViewModels: same base class and toArray() override, but custom helper methods (title(), options(), a template(): string returning the Blade view path) are allowed and expected. Translation enumeration rules for Inertia do not apply to Blade ViewModels.
  • Create vs edit forms: a form page ViewModel may accept a nullable model (?Booking $booking = null) and emit null for the model prop in create mode; the frontend derives the mode from the presence of uuid.
  • Wrong resource type at runtime: the fetchModel() guard turns a mis-wired collection (e.g. passing an array or a different model) into an explicit ObjectMissed exception instead of a silent property-access failure.
  • Multiple contexts: never grow one Resource to serve every page. If the show page needs more fields than the index table, create BookingShowResource alongside BookingIndexResource — allowlists stay minimal per context.
  • Per-layer ownership: each delivery surface owns its Resources — Dashboard and Api each keep their own BookingResource, never shared through Core.
  • JsonControllers return Resources/collections directly instead of Inertia props; the Resource rules here apply unchanged — controller shape → see the labrodev-controller skill.
  • Exports may consume IndexQueries/ViewModels but never mutate state — the same "no raw models out" rule applies.

Source: SKILL.md on GitHub

No rule matched.

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

No third-party reports yet.

Signed by skilld at 4e3053b. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub last month.

Steadyupdated 2 months ago
metadata
{
  "author": "labrodev"
}

README badge

README badge for labrodev/laravel-playbook/labrodev-viewmodel-resource