View models in Laravel

Have you ever made a controller where you had to do a lot of work to prepare variables to be passed to a view? You can move that kind of work to a so called view model. In essence, view models are simple classes that take some data, and transform it into something usable for the view.

You'll find a more detailed explanation and some good examples in this blogpost on Stitcher.io.

Laravel's native view composers are not the same as the view models provided by this package. To learn more about the differences head over to this blogpost on Stitcher.io.

Installation

You can install the package via composer:

composer require spatie/laravel-view-models

Usage

A view model is a class where you can put some complex logic for your views. This will make your controllers a bit lighter. You can create a view model by extending the provided Spatie\ViewModels\ViewModel.

class PostViewModel extends ViewModel
{
    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();
    }
}

And used in controllers like so:

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);
    }
}

In a view you can do this:

<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>

All public methods and properties in a view model are automatically exposed to the view. If you don't want a specific method to be available in your view, you can ignore it.

class PostViewModel extends ViewModel
{
    protected $ignored = ['ignoredMethod'];

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

All PHP's built in magic methods are ignored automatically.

View models as responses

It's possible to directly return a view model from a controller. By default, a JSON response with the data is returned.

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

This approach can be useful when working with AJAX submitted forms.

It's also possible to return a view directly:

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

Note that when the Content-Type header of the request is set to JSON, this approach will also return JSON data instead of a rendered view.

Exposing view functions

View models can expose functions which require extra parameters.

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

You can use these functions in the view like so:

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

Making a new view model

The package included an artisan command to create a new view model.

php artisan make:view-model HomepageViewModel

This view model will have the App\ViewModels namespace and will be saved in app/ViewModels.

or into a custom namespace, say, App\Blog

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

This view model will have the App\Blog\ViewModels namespace and will be saved in app/Blog/ViewModels.

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security

If you discover any security related issues, please email freek@spatie.be instead of using the issue tracker.

Postcardware

You're free to use this package, but if it makes it to your production environment we highly appreciate you sending us a postcard from your hometown, mentioning which of our package(s) you are using.

Our address is: Spatie, Samberstraat 69D, 2060 Antwerp, Belgium.

We publish all received postcards on our company website.

Credits

Support us

Spatie is a webdesign agency based in Antwerp, Belgium. You'll find an overview of all our open source projects on our website.

Does your business depend on our contributions? Reach out and support us on Patreon. All pledges will be dedicated to allocating workforce on maintenance and new awesome stuff.

License

The MIT License (MIT). Please see License File for more information.

mikew1/laravel-view-models