Getting Started

Minimal Setup

Installation:

composer require spatie/laravel-view-models

Publish the config (optional):

php artisan vendor:publish --provider="Spatie\ViewModels\ViewModelsServiceProvider"

First Use Case: Create a view model class (e.g., app/ViewModels/PostViewModel.php):

namespace App\ViewModels;

use Spatie\ViewModels\ViewModel;

class PostViewModel extends ViewModel
{
    public function __construct(
        public string $title,
        public string $content,
        public int $commentsCount
    ) {}
}

Usage in Controller:

use App\ViewModels\PostViewModel;

public function show(Post $post)
{
    return view('posts.show', [
        'viewModel' => PostViewModel::createFrom($post)
            ->withCommentsCount($post->comments()->count())
    ]);
}

View Access:

<h1>{{ $viewModel->title }}</h1>
<p>{{ $viewModel->content }}</p>
<span>Comments: {{ $viewModel->commentsCount }}</span>

Where to Look First

Blogpost: Laravel View Models (official guide)
Package Docs: GitHub README
Config: config/view-models.php (for customization)

Implementation Patterns

Core Workflow

Model-to-ViewModel Transformation: Use createFrom() to instantiate a view model from a model instance, then chain methods to enrich data:

PostViewModel::createFrom($post)
    ->withCommentsCount($post->comments()->count())
    ->withAuthor($post->author->name)
    ->withTags($post->tags->pluck('name'))

Dynamic Properties: Add computed properties via with() or withDynamic():

public function withDynamic(Post $post)
{
    return $this->with([
        'isPopular' => $post->views > 1000,
        'formattedDate' => $post->created_at->format('M d, Y'),
    ]);
}

View Model Factories: For complex logic, use a factory class (e.g., PostViewModelFactory):

public function create(Post $post)
{
    return new PostViewModel(
        $post->title,
        $post->content,
        $post->comments()->count(),
        $post->author->name,
    );
}

Integration with Controllers:
- Resource Controllers: Use traits like Spatie\ViewModels\Traits\ResourceController for DRY code.
- API Responses: Return view models as JSON responses:
```
return response()->json($viewModel);
```

Caching: Cache view models in controllers or factories:

$viewModel = Cache::remember("post.{$post->id}.viewmodel", now()->addHours(1), function () use ($post) {
    return PostViewModel::createFrom($post)->withCommentsCount($post->comments()->count());
});

Advanced Patterns

Nested View Models:

class PostViewModel extends ViewModel
{
    public function __construct(
        public AuthorViewModel $author,
        public CommentViewModel $latestComment
    ) {}
}

View Model Collections:

$posts = Post::all();
$viewModels = PostViewModel::collection($posts)
    ->each(fn ($vm) => $vm->withCommentsCount($vm->post->comments()->count()));

Conditional Data:

public function withDynamic(Post $post)
{
    return $this->with([
        'excerpt' => $post->isPublished ? Str::limit($post->content, 200) : null,
    ]);
}

Gotchas and Tips

Common Pitfalls

Over-Fetching Data:
- Issue: Eager-loading too much data in view models can bloat queries.
- Fix: Use with() sparingly and lazy-load relationships where possible:
```
$viewModel->withCommentsCount($post->comments()->count()); // Eager-load
$viewModel->withAuthor($post->author); // Load on demand in view model
```

Circular Dependencies:

Issue: View models referencing each other (e.g., PostViewModel → AuthorViewModel → PostViewModel).

Fix: Break cycles by flattening data or using IDs:

class AuthorViewModel extends ViewModel
{
    public function __construct(
        public string $name,
        public ?int $postId = null // Store ID instead of model
    ) {}
}

Immutable Properties:
- Issue: View models are immutable by design; modifying properties after creation fails.
- Fix: Use with() or withDynamic() to add new properties:
```
// ❌ Fails: $viewModel->newProperty = 'value';
// ✅ Works: $viewModel->with(['newProperty' => 'value']);
```

Performance with Large Collections:

Issue: Processing large collections of view models can be slow.

Fix: Use each() with batch processing or chunking:

PostViewModel::collection($posts)
    ->each(fn ($vm) => $vm->withCommentsCount($vm->post->comments()->count()))
    ->chunk(100); // Process in batches

Testing Quirks:
- Issue: View models can make unit tests harder to mock.
- Fix: Mock the factory or use partial view models in tests:
```
$viewModel = Mockery::mock(PostViewModel::class)
    ->makePartial()
    ->shouldAllowMockingProtectedMethods();
```

Debugging Tips

Log View Model Data: Use dd() or dump() to inspect view model contents:

dd(PostViewModel::createFrom($post)->withCommentsCount($post->comments()->count()));

Check for Missing Properties: Laravel will throw UndefinedProperty errors if a property isn’t defined. Use isset() in views:
```
@if (isset($viewModel->optionalProperty))
    {{ $viewModel->optionalProperty }}
@endif
```

Verify Factory Calls: Ensure factories are called correctly in controllers:

// ❌ Wrong: PostViewModel::create($post); // Missing 'from' if using model
// ✅ Correct: PostViewModel::createFrom($post);

Extension Points

Custom View Model Macros: Add reusable methods to the base ViewModel class:

use Spatie\ViewModels\ViewModel;

ViewModel::macro('withMeta', function (array $meta) {
    return $this->with($meta);
});

Usage:

PostViewModel::createFrom($post)->withMeta(['key' => 'value']);

View Model Events: Listen for view model creation/modification:

ViewModel::created(function (ViewModel $viewModel) {
    Log::info("ViewModel created: " . get_class($viewModel));
});

Custom Validation: Validate view model data before passing to views:

public function withDynamic(Post $post)
{
    $this->validate([
        'title' => 'required|max:255',
        'content' => 'required',
    ]);

    return $this->with([
        'isValid' => true,
    ]);
}

View Model Caching Strategies: Override the default caching behavior in config/view-models.php:
```
'cache' => [
    'driver' => 'redis',
    'prefix' => 'view_models',
],
```

Integration with Form Requests: Use view models to validate and transform form data:

public function rules()
{
    return [
        'title' => 'required|max:255',
        'content' => 'required',
    ];
}

public function withViewModel()
{
    return PostViewModel::create(
        $this->validated('title'),
        $this->validated('content'),
        0 // Default comments count
    );
}

Laravel View Models Laravel Package