Laravel View Models

https://github.com/spatie/laravel-view-models
Admin
Laravel View Models is a package that provides a simple way to encapsulate complex view logic in...
Tokens:3,439
Snippets:41
Trust Score:10
License:MIT
Update:7 months ago
Show doc for...
Tokens:
Raw
### Install the package

Source: https://github.com/spatie/laravel-view-models/blob/main/README.md

Use Composer to add the package to your Laravel project.

```bash
composer require spatie/laravel-view-models
```

--------------------------------

### Return ViewModel as JSON Response

Source: https://context7.com/spatie/laravel-view-models/llms.txt

Return a ViewModel directly from a controller to automatically get a JSON response. This is ideal for AJAX requests and API endpoints.

```php
<?php

namespace App\Http\Controllers;

use App\Models\Post;
use App\ViewModels\PostViewModel;
use Illuminate\Http\Request;

class PostsController
{
    // Returns JSON response by default
    public function update(Request $request, Post $post)
    {
        $post->update($request->validated());

        // Returning ViewModel directly outputs JSON
        return new PostViewModel($post);
    }

    // Response when Accept: application/json header is present:
    // {
    //     "post": {"id": 1, "title": "Updated Title", "body": "Content..."},
    //     "categories": [{"id": 1, "name": "Tech"}, {"id": 2, "name": "News"}],
    //     "indexUrl": "/posts"
    // }
}
```

--------------------------------

### Convert ViewModel to Array

Source: https://context7.com/spatie/laravel-view-models/llms.txt

Call `toArray()` to get all exposed data as an associative array. This is useful for testing, debugging, or when you need the raw data. Callable methods become closures in the resulting array.

```php
<?php

use App\ViewModels\PostViewModel;
use App\Models\User;
use App\Models\Post;

$user = User::find(1);
$post = Post::find(1);

$viewModel = new PostViewModel($user, $post);

// Get all exposed data as array
$data = $viewModel->toArray();

// Result:
// [
//     'user' => User {...},
//     'post' => Post {...},
//     'indexUrl' => '/posts',
//     'categories' => Collection {...},
//     'formatDate' => Closure {...}  // Callable methods become closures
// ]

// Test that expected keys exist
assert(array_key_exists('post', $data));
assert(array_key_exists('categories', $data));
assert(is_callable($data['formatDate']));

```

--------------------------------

### Create a ViewModel Class

Source: https://context7.com/spatie/laravel-view-models/llms.txt

Extend the base ViewModel class to expose public properties and methods to your views.

```php
<?php

namespace App\ViewModels;

use App\Models\User;
use App\Models\Post;
use App\Models\Category;
use Illuminate\Support\Collection;
use Spatie\ViewModels\ViewModel;

class PostViewModel extends ViewModel
{
    // Public properties are automatically exposed to the view
    public $user;
    public $post;
    public $indexUrl = null;

    public function __construct(User $user, Post $post = null)
    {
        $this->user = $user;
        $this->post = $post;
        $this->indexUrl = action([PostsController::class, 'index']);
    }

    // Methods without parameters: return value is exposed as $post
    public function post(): Post
    {
        return $this->post ?? new Post();
    }

    // Return value is exposed as $categories
    public function categories(): Collection
    {
        return Category::canBeUsedBy($this->user)->get();
    }
}
```

--------------------------------

### Generate a new View Model

Source: https://github.com/spatie/laravel-view-models/blob/main/README.md

Use the artisan command to scaffold a new view model class in the default or a custom namespace.

```bash
php artisan make:view-model HomepageViewModel
```

```bash
php artisan make:view-model "Blog/PostsViewModel"
```

--------------------------------

### Use View Model in Controller

Source: https://github.com/spatie/laravel-view-models/blob/main/README.md

Instantiate the view model and pass it to the view function.

```php
class PostsController
{
    public function create()
    {
        $viewModel = new PostViewModel(
            current_user()
        );
        
        return view('blog.form', $viewModel);
    }
    
    public function edit(Post $post)
    {
        $viewModel = new PostViewModel(
            current_user(), 
            $post
        );
    
        return view('blog.form', $viewModel);
    }
}
```

--------------------------------

### Generate New ViewModel with Artisan

Source: https://context7.com/spatie/laravel-view-models/llms.txt

Use the `make:view-model` Artisan command to generate new ViewModel classes with the correct namespace and directory structure. You can specify custom subdirectories and force overwrites.

```bash
# Create a view model in app/ViewModels/HomepageViewModel.php
php artisan make:view-model HomepageViewModel

# Create in a custom subdirectory: app/Blog/ViewModels/PostsViewModel.php
php artisan make:view-model "Blog/PostsViewModel"

# Force overwrite if file exists
php artisan make:view-model HomepageViewModel --force
```

```php
<?php

namespace App\ViewModels;

use Spatie\ViewModels\ViewModel;

class HomepageViewModel extends ViewModel
{
    public function __construct()
    {
        //
    }
}
```

--------------------------------

### Define a View Model

Source: https://github.com/spatie/laravel-view-models/blob/main/README.md

Create a class extending Spatie\ViewModels\ViewModel to encapsulate view data and logic.

```php
class PostViewModel extends ViewModel
{
    public $user;

    public $post;
    
    public $indexUrl = null;

    public function __construct(User $user, Post $post = null)
    {
        $this->user = $user;
        $this->post = $post;
        
        $this->indexUrl = action([PostsController::class, 'index']); 
    }
    
    public function post(): Post
    {
        return $this->post ?? new Post();
    }
    
    public function categories(): Collection
    {
        return Category::canBeUsedBy($this->user)->get();
    }
}
```

--------------------------------

### Return View Model as View Response

Source: https://github.com/spatie/laravel-view-models/blob/main/README.md

Explicitly define the view template when returning a view model from a controller.

```php
class PostsController
{
    public function update(Request $request, Post $post)
    {
        // …
        
        return (new PostViewModel($post))->view('post.form');
    }
}
```

--------------------------------

### Use ViewModel in Controllers

Source: https://context7.com/spatie/laravel-view-models/llms.txt

Pass the instantiated ViewModel directly to the view helper to make its data available in the template.

```php
<?php

namespace App\Http\Controllers;

use App\Models\Post;
use App\ViewModels\PostViewModel;

class PostsController
{
    public function create()
    {
        // Create view model with just the user
        $viewModel = new PostViewModel(current_user());

        // Pass directly to view - all public methods/properties become available
        return view('blog.form', $viewModel);
    }

    public function edit(Post $post)
    {
        // Create view model with user and existing post
        $viewModel = new PostViewModel(current_user(), $post);

        return view('blog.form', $viewModel);
    }
}
```

--------------------------------

### Return View with ViewModel

Source: https://context7.com/spatie/laravel-view-models/llms.txt

Use the `view()` method on a ViewModel to specify a Blade template for rendering. The response type automatically switches between HTML and JSON based on the request's `Accept` header.

```php
<?php

namespace App\Http\Controllers;

use App\Models\Post;
use App\ViewModels\PostViewModel;
use Illuminate\Http\Request;

class PostsController
{
    public function show(Post $post)
    {
        // Chain view() to specify the template
        return (new PostViewModel($post))->view('posts.show');
    }

    public function edit(Post $post)
    {
        // Pass additional data to the view
        return (new PostViewModel(current_user(), $post))
            ->view('posts.form', ['editing' => true]);

        // If request has Accept: application/json header,
        // JSON is returned instead of the rendered view
    }
}
```

--------------------------------

### Return View Model as JSON Response

Source: https://github.com/spatie/laravel-view-models/blob/main/README.md

Returning a view model directly from a controller defaults to a JSON response.

```php
class PostsController
{
    public function update(Request $request, Post $post)
    {
        // …
        
        return new PostViewModel($post);
    }
}
```

--------------------------------

### Expose functions in a View Model

Source: https://github.com/spatie/laravel-view-models/blob/main/README.md

Define public methods in a class extending ViewModel to make them available in your Blade templates.

```php
class PostViewModel extends ViewModel
{
    public function formatDate(Carbon $date): string
    {
        return $date->format('Y-m-d');
    }
}
```

--------------------------------

### Enable Snake Case Property Names in ViewModel

Source: https://context7.com/spatie/laravel-view-models/llms.txt

Set `$snakeCase = true` in your ViewModel to automatically convert camelCase property and method names to snake_case when exposing them to views.

```php
<?php

namespace App\ViewModels;

use Spatie\ViewModels\ViewModel;

class ArticleViewModel extends ViewModel
{
    // Enable snake_case conversion
    protected $snakeCase = true;

    public $publishedDate = '2024-01-15';

    public function featuredArticle()
    {
        return Article::featured()->first();
    }

    public function relatedPosts()
    {
        return Post::related($this->article)->get();
    }
}

// In Blade template, use snake_case names:
// $published_date (instead of $publishedDate)
// $featured_article (instead of $featuredArticle)
// $related_posts (instead of $relatedPosts)
```

--------------------------------

### Ignore Methods in View Model

Source: https://github.com/spatie/laravel-view-models/blob/main/README.md

Specify methods to exclude from being exposed to the view using the $ignore property.

```php
class PostViewModel extends ViewModel
{
    protected $ignore = ['ignoredMethod'];

    // …
    
    public function ignoredMethod() { /* … */ }
}
```

--------------------------------

### Expose Callable Methods in ViewModel

Source: https://context7.com/spatie/laravel-view-models/llms.txt

Methods with parameters in a ViewModel are exposed as callable closures in Blade views. This allows passing arguments directly within your templates.

```php
<?php

namespace App\ViewModels;

use Carbon\Carbon;
use Spatie\ViewModels\ViewModel;

class PostViewModel extends ViewModel
{
    public $post;

    public function __construct(Post $post)
    {
        $this->post = $post;
    }

    // Method with parameter becomes a callable in the view
    public function formatDate(Carbon $date): string
    {
        return $date->format('F j, Y');
    }

    // Another callable method example
    public function truncate(string $text, int $length = 100): string
    {
        return strlen($text) > $length
            ? substr($text, 0, $length) . '...'
            : $text;
    }
}
```

```blade
{{-- Call methods with parameters directly in Blade --}}
<p>Published: {{ $formatDate($post->created_at) }}</p>
<p>Updated: {{ $formatDate($post->updated_at) }}</p>

{{-- Use the truncate callable --}}
<p class="excerpt">{{ $truncate($post->body, 150) }}</p>
```

--------------------------------

### Access View Model Data in Blade

Source: https://github.com/spatie/laravel-view-models/blob/main/README.md

Public properties and methods of the view model are accessible as variables in the Blade template.

```blade
<input type="text" value="{{ $post->title }}" />
<input type="text" value="{{ $post->body }}" />

<select>
    @foreach ($categories as $category)
        <option value="{{ $category->id }}">{{ $category->name }}</option>
    @endforeach
</select>

<a href="{{ $indexUrl }}">Back</a>
```

--------------------------------

### Call View Model functions in Blade

Source: https://github.com/spatie/laravel-view-models/blob/main/README.md

Invoke methods exposed by the view model directly within your Blade templates.

```blade
{{ $formatDate($post->created_at) }}
```

--------------------------------

### Access Data in Blade Views

Source: https://context7.com/spatie/laravel-view-models/llms.txt

Access public properties and method return values as variables within your Blade templates.

```blade
{{-- Access data from public methods --}}
<input type="text" name="title" value="{{ $post->title }}" />
<input type="text" name="body" value="{{ $post->body }}" />

{{-- Loop through collection returned by categories() method --}}
<select name="category_id">
    @foreach ($categories as $category)
        <option value="{{ $category->id }}">{{ $category->name }}</option>
    @endforeach
</select>

{{-- Access public property directly --}}
<a href="{{ $indexUrl }}">Back to Posts</a>
```
Tokens:
Raw