Laravel Livewire: an introduction

Feb 07, 2021

Laravel Livewire is a great framework for creating interactive web apps without writing any JavaScript. In this tutorial we’re going to make a few components using Laravel Livewire so we can see the power of this framework.

Setting up

Important: Livewire requires you to use Laravel.

You can install Livewire using Composer:

composer require livewire/livewire

Next, you have to include Livewire’s assets on your page:

<livewire:styles /> <!-- Styles -->
<livewire:scripts /> <!-- Scripts -->

And that was it! Now you can use Livewire.

The counter

A typical example of Livewire is the counter. Although it may not be really useful to use Livewire in this situation, it does however really show the power of Livewire.

First, we are gonna make a new Livewire component:

php artisan livewire:make counter

Now Livewire has made two files: a Counter.php class and a counter.blade.php view.

Next we’ll go to the Counter.php class and add this code:

<?php

namespace App\Http\Livewire;

use Livewire\Component;

class Counter extends Component
{
    public int $count = 0;

    public function render()
    {
        return view('counter');
    }

    public function increment()
    {
        $this->count++;
    }

    public function decrement()
    {
        $this->count--;
    }
}

And now we’ll add this in our counter.blade.php view:

<div>
    <h1></h1>
    
    <button wire:click="increment">+</button>
    <button wire:click="decrement">-</button>
</div>

Finally, we have to include the component in our blade view:

<livewire:counter />

And that’s it! This is all we have to do to create a working counter in Laravel Livewire.

Note: If you want to create a counter in a real-project, you probably don’t want to do it using Livewire, because there are far simpler alternatives using only JS.

How does this work?

Now that we have had a look at the awesomeness of Livewire, let’s explain how this counter example works.

1. Livewire renders the component at the first-page load, so it’s SEO-friendly
2. When a user does something (such as clicking a button), Livewire’s JS makes a request to the server
3. The server handles the request and then Livewire rerenders the component.

Forms with Livewire

A better use-case for Livewire are forms. So let’s create a form where a user can create a new post.

We’ll start by creating a new component.

php artisan livewire:make create-post

And for the sake of simplicity, a post has a title and a body. So we have to add those fields to our class.

<?php

namespace App\Http\Livewire;

use App\Models\Post;
use Livewire\Component;

class CreatePost extends Component
{
    public string $title = '';

    public string $body = '';

    public function render()
    {
        return view('create-post');
    }

    public function createPost()
    {
        $post = Post::create([
            'title' => $this->title,
            'body' => $this->body
        ]);

        return redirect()->route('posts.show', $post);
    }
}

And in our form we’ll use the wire:model attribute to connect the input or textarea to our Livewire property.

<div>
    <h1>New Post</h1>

    <!-- Title -->
    <label for="title">Title</label>
    <input type="text" name="title" id="title" wire:model="title" />

    <!-- Body -->
    <label for="body">Body</label>
    <textarea name="body" id="body" wire:model="body"></textarea>
</div>

Now our form works! You can click on the submit button and it’ll create a new post!

Livewire’s validation

It’s time for some validation. We can do that really simple using Livewire. First we’ll add a $rules property to our component.

protected $rules = [
    'title' => ['required', 'string', 'max:255'],
    'body' => ['required', 'string']
];

And next, we’ll tell Livewire to validate before creating the post.

public function createPost()
{
    $this->validate();

    $post = Post::create([
        'title' => $this->title,
        'body' => $this->body
    ]);

    return redirect()->route('posts.show', $post);
}

Finally we have to display the validation error messages in the component view.

<div>
    <h1>New Post</h1>

    <!-- Title -->
    <label for="title">Title</label>
    <input type="text" name="title" id="title" wire:model="title" />
    @error('title')<span></span>@enderror

    <!-- Body -->
    <label for="body">Body</label>
    <textarea name="body" id="body" wire:model="body"></textarea>
    @error('body')<span></span>@enderror

    <!-- Submit button -->
    <button wire:click="createPost">Create Post</button>
</div>

Real-time validation

Now that we have added validation, it is really easy to add real-time validation with Livewire. This is the only method you have to add:

public function updated($property)
{
    $this->validateOnly($property);
}

How does this work? When a field (property) is updated, Livewire automatically calls the updated method, from where the validateOnly method is called which validates one field instead of all.

So in theory you could also just say validate, but then the whole form turns full of error messages before the user has typed anything. And that’s not very user-friendly.

Turbolinks and SPA’s

With Livewire you can easily create SPA’s. All you have to do is add those two lines:

<script src="https://cdnjs.cloudflare.com/ajax/libs/turbolinks/5.2.0/turbolinks.js"></script>
<script src="https://cdn.jsdelivr.net/gh/livewire/turbolinks@v0.1.x/dist/livewire-turbolinks.js" data-turbolinks-eval="false" data-turbo-eval="false"></script>

And now your application will use Turbolinks and the Livewire Turbolinks adapter.

Testing Livewire

Livewire is easy to test using PHPUnit. You can learn more at the Livewire docs.

Conclusion

To conclude, Livewire is a great option for writing interactive apps when you don’t want to write JavaScript or when you want it to be SEO-friendly. It is a framework full of features and I’ve just covered the basics.

These are some great features of Livewire:

And much more.

I hope you liked this tutorial. If you did so, please leave a comment.

Laravel Api Controller

Basic CRUD API Methods that can be extended for your models by default has a list, show, update, add and delete endpoint to interact with your model.

Installation

Install via composer

composer require phpsa/laravel-api-controller

Publish Configuration File (optional – if you need to change any of the default configurations)

php artisan vendor:publish --provider="Phpsa\LaravelApiController\ServiceProvider" --tag="config"

Usage

CLI Commands

• artisan make:api {ControllerName} to generate the controller
• artisan make:api:policy to generate a policy file
• artisan make:api:resource to geneate the response resource

This will create a Api/ModelNameController for you and you will have the basic routes in place as follows:

• GET api/v1/{model_name} – list all/paged/filtered (class::index)
• GET api/v1/{model_name}/$id – Show a specified id (class::show)
• POST api/v1/{model_name} – Insert a new record (class::store)
• PUT api/v1/{model_name}/$id – Update an existing record (class::update)
• DELETE api/v1/{model_name}/$id – Delete an existing record (class::destroy)

You can override the methods by simply putting in your own methods to override – method names in braces above

Events

• POST (class::store) – triggers a new Phpsa\LaravelApiController\Events\Created Event which has the new record available as $record
• PUT (class::update) – triggers a new Phpsa\LaravelApiController\Events\Updated Event which has the updated record available as $record
• DELETE (class::destry) – triggers a new Phpsa\LaravelApiController\Events\Deleted Event which has the deleted record available as $record

Policies

Policies: https://laravel.com/docs/6.x/authorization#generating-policies

Generate with php artisan make:policy PostPolicy --model=Post

• Get list – calls the viewAny policy
• Get single – calls the view policy
• Post New – calls the create policy
• Put Update – calls the update policy
• Delete item – calls the delete policy

Query/Data modifiers in policies for the api endpoints

• qualifyCollectionQueryWithUser($user, $repository) -> return void – add any queries to the repository (ie ->where(‘x’,’))
• qualifyItemQueryWithUser($user, $repository)-> return void – add any queries to the repository (ie ->where(‘x’,’))
• qualifyStoreDataWithUser($data) – return the updated data array
• qualifyUpdateDataWithUser($data) – return the updated data array

Resources / Collections (Transforming)

Resources: https://laravel.com/docs/6.x/eloquent-resources

Generate with
php artisan make:apiresource UserResource and php artisan make:resource UserCollection

Change the Resource to extend from:

use Phpsa\LaravelApiController\Http\Resources\ApiResource for your resource
use Phpsa\LaravelApiController\Http\Resources\ApiCollection for your resource collection

in your controller override the following params:

	protected $resourceSingle = UserResource::class;
	protected $resourceCollection = UserCollection::class;

Snake vs Camel

• middleware to convert all camel to snake: Phpsa\LaravelApiController\Http\Middleware\SnakeCaseInputs
• set request header X-Accept-Case-Type to either snake or camel to alter your data response

Filtering

For the get command you can filter by using the following url patterns

In / Not In

You can pass to the filters an array of values
ie: filter[user_id]=1||2||||4||7 or filter[user_id!]=55||33

Null / Not Null (introduced 1.23.0)

If you need to filter on whether a field is null or not null, you can use the filter param as of version 1.23.0 EG: filter[age]=NULL or filter[age!]=NULL. Note that NULL must be uppercase.

Older versions
Add a scope to your model: eg

public function scopeAgeNull(Builder $builder, $isNull = true){
  $isNull ? $builder->whereNull('age') : $builder->whereNotNull('age');
}

Add to your allowedScopes and can then be called in url as ?ageNull=1 for where null and ?ageNull=0 for where age not null

Scopes

In addition to filtering, you can use Laravel’s Eloquent Query Scopes to do more complex searches or filters.
Simply add an $allowedScopes to your ApiResource, and that scope will be exposed as a query parameter.

Assuming you have a scopeFullname defined on your Eloquent Model, you can expose this scope to your API as follows:

protected static $allowedScopes = [
  'fullname'
];

Given the above $allowedScopes array, your API consumers will now be able to request ?fullname=John. The query parameter value will be passed to your scope function in your Eloquent Model.

Filtering on related models

You can easily filter using any related model that is configured for include. Simply specify ?filter[model.field]=123 in your query string. The same filter options above apply to related fields.

Fields, Relationships, Sorting & Pagination

Fields

By default all fields are returned, you can limit that to specific fields in the following ways:

• Api Controller parameter $defaultFields default as protected $defaultFields = ['*']; – switch to include an array of fields
• fields param in url querystring: ie fields=id,name,age = will only return those, this will also override the above.
• in your response resource you can set the static::allowedFields to lock down which fields are returnable
• addfields and removefields params in url querystring will work with these.
• Use laravel eloquent model $appends property to automatically include custom attribute accessors.

Relationships

• Using the relationships defined in your models, you can pass a comma delimited list eg include=join1,join2 which will return those joins (one or many).

Simply add a protected static $mapResources to your Resource to define which resources to assign your related data. E.e., for a one to many relationship, you should specify a collection, and a one-to-one relationship specify the related resource directly. This will allow the API to properly format the related record.

    protected static $mapResources = [
        'notes' => NotesCollection::class,
        'owner' => OwnerResource::class
    ];

• You can automatically update and create related records for most types of relationships. Just include the related resource name in your POST or PUT request.

For BelongsToMany or MorphToMany relationships, you can choose the sync strategy. By default, this will take an additive strategy. That is to say, related records sent will be ADDED to any existing related records. On a request-by-request basis, you can opt for a sync strategy which will remove the pivot for any related records not listed in the request. Note the actual related record will not be removed, just the pivot entry.

To opt for the sync behavaiour, set ?sync[field]=true in your request.

Sorting

• Sorts can be passed as comma list aswell, ie sort=age asc or sort=age asc,name desc,eyes – generates sql of sort age asc and sort age asc, name desc, eyes asc respectively
• Default sort can also be added on the controller using by overrideing the protected $defaultSort = null; parameter

Pagination

• pagination can be enabled/disbled on the controller by overriding the protected $defaultLimit = 25; on the controller
• pagination can also be passed via the url using limit=xx&page=y
• pagination can also be limited to a max per page by overriding the protected $maximumLimit = false; parameter

Validation

• When Posting a new record, validation can be done by adding a rulesForCreate method to your controller returning an array eg

[
    'email' => 'required|email',
    'games' => 'required|numeric',
]

see https://laravel.com/docs/5.8/validation#conditionally-adding-rules

• for updating a record, add a method rulesForUpdate per above.

Defaults

The following parameters are set in the Base Api controller and can be overwritten by your Controller on a case by case basis:

• DEPRECATED protected $resourceKeySingular = 'data';

• DEPRECATED protected $resourceKeyPlural = 'data';

• protected $resourceSingle = JsonResource::class; Collection to use for your single resource

• protected $resourceCollection = ResourceCollection::class; Collection to use for your resource collection

• protected $defaultFields = ['*']; Default Fields to respond with

• protected $defaultSort = null; Set the default sorting for queries.

• protected $defaultLimit = 25; Number of items displayed at once if not specified. (0 = maximumLimit)

• protected $maximumLimit = 0; Maximum limit that can be set via $_GET[‘limit’]. – this ties in with the defaultLimit aswell, and if wanting to disable pagination , both should be 0. ) will allow all records to be returned in a single call.

• protected $unguard = false; Do we need to unguard the model before create/update?

Scopes

SoftDeleted Records

add the Phpsa\LaravelApiController\Model\Scopes\WithSoftDeletes trait to your model,
add to your resource file:

class MyModelResource extends ApiResource
{

 protected static $allowedScopes = [
        'withTrashed',
        'onlyTrashed'
    ];

you can now append withTrashed=1 or onlyTrashed=1 to your query.

Responses

you can override responses for each point by overriding the following protected methods:

• handleIndexResponse
• handleStoreResponse
• handleShowResponse
• handleUpdateResponse
• handleDestroyResponse

Security

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

Credits

Sponsors