Forem: Elisha Ukpong

Laravel Events and Listeners

Elisha Ukpong — Sun, 19 Jul 2020 23:09:07 +0000

Previously, I wrote about Laravel Observers and mentioned it as a feature of Laravel framework that I love, since I came across it.

Read about it here

Today, I will be shedding light on another part of the Laravel framework that interests me too, events and listeners.

Events are just ways to alert your application that an action has happened, and the events can be dispatched at any point of your application, the controller, the model, the middleware, anywhere — even in the blade files(you shouldn’t do this, but you get my point).

Listeners, like the name implies, listens for events that occur in your application, but they do not just listen to any event, each listener must be mapped to an event before it listens for that event.

For a listener to respond to a dispatched event, the listener class must be mapped to a particular event class. These mappings happen in the EventServiceProvider class which can be found in the app\Providers folder.

An event can have multiple listeners mapped to it and when it is dispatched, all listening classes will be triggered in succession following the order in which it is mapped.

//Default EventServiceProvider Class


<?php

namespace App\Providers;

use Illuminate\Auth\Events\Registered;
use Illuminate\Auth\Listeners\SendEmailVerificationNotification;
use Illuminate\Foundation\Support\Providers\EventServiceProvider as ServiceProvider;
use Illuminate\Support\Facades\Event;

class EventServiceProvider extends _ServiceProvider_  
{
_/\*\*  
     \* The event listener mappings for the application.  
     \*  
     \*_ **_@var_** _array  
     \*/_ protected $listen = [
        Registered::class => [
            SendEmailVerificationNotification::class,
        ],
    ];

_/\*\*  
     \* Register any events for your application.  
     \*  
     \*_ **_@return_** _void  
     \*/_ public function boot()
    {
        parent::_boot_();

        //
    }
}

Creating an event and listener class

To create an event class, make use of the make:event artisan command:

php artisan make:event

This command will create a new class into the app\Events folder of your application and that is all you need to create an event class.

To create a listener class, make use of the make:listener artisan command:

php artisan make:listener

This command, like in the Event creation, will create a new class into the app\Listeners folder of your application and that is all you need to create a listener class.

Another way of creating events and listeners, this way might even be termed easier than the ones earlier mentioned, is to register events and listeners in the EventServiceProvider class, then run:

php artisan event:generate

This command will scan through the EventServiceProvider class and generate the missing events and listeners based on registration.

You might already be wondering how to register an event and map a listener to it, yea? To do that, follow the pattern below:

_//Event Service Provider Class_

_/\*\*  
 \* The event listener mappings for the application.  
 \*  
 \*_ **_@var_** _array  
 \*/_ protected $listen = [
    'Event Class' => [
        'Listener Class',
        'Another Listener Class',
        'Yet Another Listener Class',
    ],
];

Like I earlier said, you can map more than one listener to a particular event and it will get processed in succession, following the order in which they are mapped.

Dispatching an event

To dispatch your event and trigger the listeners, there are two methods known to me as at the time of this writing:

event(new EventClass());
EventClass::dispatch();

If your event uses the Illuminate\Foundation\Events\Dispatchable trait, you may call the static dispatch method on the event. Any arguments passed to the dispatch method will be passed to the event's constructor.

You should note that public properties declared in the event class, can be accessed in the listener class which is mapped to it.

//Registered Event using in register controller.

<?php

namespace Illuminate\Auth\Events;

use Illuminate\Queue\SerializesModels;

class Registered
{
    use SerializesModels;

_/\*\*  
     \* The authenticated user.  
     \*  
     \*_ **_@var_** _\Illuminate\Contracts\Auth\Authenticatable  
     \*/_ public $user;

_/\*\*  
     \* Create a new event instance.  
     \*  
     \*_ **_@param_** _\Illuminate\Contracts\Auth\Authenticatable $user  
     \*_ **_@return_** _void  
     \*/_ public function \_\_construct($user)
    {
        $this->user = $user;
    }
}

<?php

namespace App\Listeners;

use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Queue\InteractsWithQueue;

class RegisteredListener
{
_/\*\*  
     \* Create the event listener.  
     \*  
     \*_ **_@return_** _void  
     \*/_ public function \_\_construct()
    {
        //
    }

_/\*\*  
     \* Handle the event.  
     \*  
     \*_ **_@param_** _object $event  
     \*_ **_@return_** _void  
     \*/_ public function handle($event)
    {
        $event->user 
        //this will have the content of the user property from the event class
    }
}

Use Case

A very straightforward use-case of events and listeners would be the default user creation flow on the Laravel Framework.

For a lot of applications, there might be numerous processes that happen right after a user is created, and having all these logic in the controller method, might not just cluster up the controller method but for every additional process I want to take after a user signs up on my app.

I will have to go back to that method and do edits which defies both the Open/Close and the Single Responsibility Principle of the S.O.L.I.D principles, events, and listeners come to the rescue.

What is S.O.L.I.D Principle?

S.O.L.I.D is an acronym that represents five principles of object-oriented programming and code design theorized by our beloved Uncle Bob (Robert C. Martin) by the year 2000. The author Michael Feathers was responsible for creating the acronym:

[S]ingle Responsibility Principle

[O]pen/Closed Principle

[L]iskov Substitution Principle

[I]nterface Segregation Principle

[D]ependency Inversion Principle

Single Responsibility Principle (SRP) — A class should have one, and only one, reason to change.

Open/Closed Principle (OCP) — You should be able to extend a classes behavior, without modifying it.

Excerpts taken from: https://medium.com/@mari_azevedo/s-o-l-i-d-principles-what-are-they-and-why-projects-should-use-them-50b85e4aa8b6

On your default Register controller, you will see that a trait called RegisterUsers is used and this houses most of the logic for user creation. Inside the trait, there is a register method and that will be our concern.

_/\*\*  
 \* Handle a registration request for the application.  
 \*  
 \*_ **_@param_** _\Illuminate\Http\Request $request  
 \*_ **_@return_** _\Illuminate\Http\Response  
 \*/_ public function register(Request $request)
{
    $this->validator($request->all())->validate();

**event(new Registered($user = $this->create($request->all())));**

    $this->guard()->login($user);

    if ($response = $this->registered($request, $user)) {
        return $response;
    }

    return $request->wantsJson()
                ? new Response('', 201)
                : redirect($this->redirectPath());
}

In the above code snippet, take notice of the emboldened line of code, this dispatches an event called Registered, for every time a user is registered on your application which can be listened to, by creating a listener class and mapping it to the event in the EventServiceProvider.

Imagine I am building a student portal and when a student is registered I have to:

Assign the student a class
Assign the student a seat in the class
Assign the student a lab partner
Assign the student a library card, and the list goes on and on and on.

A typical way to do this might be to dump all the logic into the register controller method, like below:

_/\*\*  
 \* Handle a registration request for the application.  
 \*  
 \*_ **_@param_** _\Illuminate\Http\Request $request  
 \*_ **_@return_** _\Illuminate\Http\Response  
 \*/_ public function register(Request $request)
{
    $this->validator($request->all())->validate();

    event(new Registered($user = $this->create($request->all())));

   //Assign the student a class
   //Assign the student a seat in the class
   //Assign the student a lab partner
   //Assign the student a library card
   //more

    $this->guard()->login($user);

    if ($response = $this->registered($request, $user)) {
        return $response;
    }

    return $request->wantsJson()
                ? new Response('', 201)
                : redirect($this->redirectPath());
}

While this may work, it breaks more than one principle as mentioned earlier. A way around this will be to create listeners and map it to the Registered event.

_//Event Service Provider Class_

_/\*\*  
 \* The event listener mappings for the application.  
 \*  
 \*_ **_@var_** _array  
 \*/_ protected $listen = [
    Registered::class => [
        AssignClassToStudent::class,
        AssignSeatToStudent::class,
        AssignLabPartnerToStudent::class,
        AssignLibraryCardToStudent::class,
    ],
];

With our provider having the above content, the php artisan event:generate command will generate 4 listener class in the app\Listener folder, but for brevity, I’ll continue with one — the assignClassToStudent listener

<?php

namespace App\Listeners;

use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Queue\InteractsWithQueue;

class assignClassToStudent
{
_/\*\*  
     \* Create the event listener.  
     \*  
     \*_ **_@return_** _void  
     \*/_ public function \_\_construct()
    {
        //
    }

_/\*\*  
     \* Handle the event.  
     \*  
     \*_ **_@param_** _object $event  
     \*_ **_@return_** _void  
     \*/_ public function handle($event)
    {
        $event->user->assignClassToStudentLogic();
    }
}

Following this pattern means, if there is more logic to do after a user is registered, you do not need to edit the register method, you just need to spin up a new listener and map it to the event. This way the register method only handles student registration and the other listeners handle the other responsibilities.

The End.

Introducing Laravel Observers.

Elisha Ukpong — Sun, 19 Jul 2020 07:29:10 +0000

Laravel Observers

Laravel framework comes with lots of awesome features, the outstanding one for me is the model observers.

According to the Laravel framework’s documentation:

If you are listening for many events on a given model, you may use observers to group all of your listeners into a single class. Observers classes have method names which reflect the Eloquent events you wish to listen for. Each of these methods receives the model as their only argument. The make:observer Artisan command is the easiest way to create a new observer class.

The observers helps me to declutter my controller of clean-up codes that I might have to run before or after making a model event, and also gives me a way to plug into the model’s event’s lifecycle and run any logic I might see fit.

The model events that can be observed are spread across the model’s CRUD and includes:

Retrieved
Creating
Created
Updating
Updated
Saving
Saved
Deleting
Deleted
Restoring
Restored

The above events can be observed for every model in the Laravel Framework and business logic attached to it, you can also dispatch custom events from the observer and listen to it from other parts of your application.

You might not see yourself using the observer class just yet and that is fine, having fair knowledge about it too, is okay.

Before that, to create an observer class, run:

php artisan make:observer

(replace observerName with the name of the model you are observing).

This will create a folder in your application’s app directory called Observers and store the observer class.

<?php

namespace App\Observers;

class BankObserver
{
    // an empty observer class
}

From here you can populate the classes with methods that match events I listed earlier, it is worthy to note that you can attach a model to an observer when creating the observer, like:

php artisan make:observer -m=

This will create the class with some method filled in by default, see below.

<?php

namespace App\Observers;

use App\Task;

class Task
{
_/\*\*  
     \* Handle the task "created" event.  
     \*  
     \*_ **_@param_** _\App\Task $task  
     \*_ **_@return_** _void  
     \*/_ public function created(Task $task)
    {
        //
    }

_/\*\*  
     \* Handle the task "updated" event.  
     \*  
     \*_ **_@param_** _\App\Task $task  
     \*_ **_@return_** _void  
     \*/_ public function updated(Task $task)
    {
        //
    }

_/\*\*  
     \* Handle the task "deleted" event.  
     \*  
     \*_ **_@param_** _\App\Task $task  
     \*_ **_@return_** _void  
     \*/_ public function deleted(Task $task)
    {
        //
    }

_/\*\*  
     \* Handle the task "restored" event.  
     \*  
     \*_ **_@param_** _\App\Task $task  
     \*_ **_@return_** _void  
     \*/_ public function restored(Task $task)
    {
        //
    }

_/\*\*  
     \* Handle the task "force deleted" event.  
     \*  
     \*_ **_@param_** _\App\Task $task  
     \*_ **_@return_** _void  
     \*/_ public function forceDeleted(Task $task)
    {
        //
    }
}

You might be wondering what model action triggers what observer action, I’ll briefly explain the different methods and what triggers them.

Retrieved — This observer method is called when a model record is retrieved from the database.

Model::findOrFail($id); //this triggers the retrieved method in the observer class

Creating — This observer method is called when a model record is in the process of creation, and not yet stored into the database, this is before the id, and default timestamps are generated for the model, at this point you can dynamically check for and assign a default value to a missing column.
Created — This observer method is called after a model record is created successfully. If there is an error in the process of creation, say a missing column data, this method doesn’t get called.

Model::create([]); //this triggers the creating method first, then created method in the observer class.

Updating — This observer method is called when a model record is in the updating process, at this point, the updates has not yet been persisted to the database.
Updated — This observer method is called after a model record is updated successfully. If there is an error in the process of updating, this method doesn’t get called.

Model::update([]); //this triggers the creating method first, then created method in the observer class.

Saving and Saved — These model observer methods might seem a bit like a swiss army knife, it gets called before and after any event that requires persistence of data to the database, so if you’re creating a new model record, the saving method runs first, then the creating method, then the created method and finally the saved method, the same routine applies when updating a model, saving, updating, updated, saved.
Deleting — This observer method is called when a model record is in the deletion process, at this point, the record has not yet been deleted from the database, and using its id to retrieve it from the database will return appropriate data.
Deleted — This observer method is called after a model record is successfully deleted, at this point, the record has been deleted from the database.

Model::destroy($id);

Restoring and Restored — These observer methods are called when a deleted model record is restored (using soft deletes implementation)

Important things to note:

The updating and updated methods only run when the update changes a column of the model in the database, as such, if the update request does not effect a change, the updating and updated observers don’t trigger, only the saving and saved methods get triggered.
When restoring a deleted record, series of methods gets triggered one after the other, retrieved, restoring, saving, updating, updated, saved, then restored.

In any case where you want to make a model event without triggering any observer method, you can save it without observer events. An example of a method to use when creating a model without triggering any of the events:

public function saveQuietly(array $options = [])
{
    return static::_withoutEvents_(function () use ($options) {
        return $this->save($options);
    });
}

Note: This method should be added in the respective model.

You can refactor it to suit other model events, as necessary.

Finally, the last part, binding the observer to a particular model.

This can be done in the boot method of the AppServiceProvider’s class:

_/\*\*  
 \* Bootstrap any application services.  
 \*  
 \*_ **_@return_** _void  
 \*/_ public function boot()
{
    Model::_observe_(Observer::class);
}

Model is the model to be observed and observer is the observer class

This ends the introduction to Laravel observers, and I hope it was enlightening to you.

Overriding Laravel’s Default Models Folder using Artisan Command

Elisha Ukpong — Fri, 17 Jul 2020 12:55:57 +0000

A few weeks ago, the creator of Laravel, Taylor Otwell made a poll asking the framework’s users how they arrange their model files in the app folder.

Taylor Otwell 🏜

@taylorotwell

Spicy Monday poll... don't respond with some "I follow DDD and put them in contextual directories" thing either 💋

21:05 PM - 29 Jun 2020

68 339

The framework default stores all models in the app folder directly but most developers and me inclusive would prefer to have a specific models folder to house all models.

Default Laravel Models arrangement.

My way of arranging models.

Following this method of arranging models comes with a bit of tediousness as the folder name has to be specified as a namespace when creating the model using the artisan command. To create a model the default way, you can run this command below in the terminal:

php artisan make:model Bank

This command will create a new Bank model class and put the file directly in the app folder.

To create a model directly into any other folder, for me, the Models folder, this has to be specified when running the command, see below:

php artisan make:model Models\Bank

While doing this might not look like a big deal any time you want to create a new model, but having more than one developer on the project or creating a lot of models over time, you might tend to forget adding the _Models\_ prefix every time and that will create the model into the default app folder, not what we want.

To fix this, we can extend the Laravel’s default model creation artisan command and edit the default namespace/folder so we do not have to prepend the namespace/folder name while creating a new model.

Note: The folder name, is the namespace name too.

Firstly, create a new artisan command:

php artisan make:command ModelMakeCommand

This creates a new command class/file in the app\Console\Commands folder with contents:

<?php

namespace App\Console\Commands;

use Illuminate\Console\Command;

class ModelMakeCommand extends Command
{
_/\*\*  
     \* The name and signature of the console command.  
     \*  
     \*_ **_@var_** _string  
     \*/_ protected $signature = 'command:name';

_/\*\*  
     \* The console command description.  
     \*  
     \*_ **_@var_** _string  
     \*/_ protected $description = 'Command description';

_/\*\*  
     \* Create a new command instance.  
     \*  
     \*_ **_@return_** _void  
     \*/_ public function \_\_construct()
    {
        parent::_\_\_construct_();
    }

_/\*\*  
     \* Execute the console command.  
     \*  
     \*_ **_@return_** _int  
     \*/_ public function handle()
    {
        return 0;
    }
}

Secondly, we will change the class that our ModelMakeClass extends from Illuminate\Console\Command to Illuminate\Foundation\Console\ModelMakeCommand

Thirdly, we will empty the ModelMakeClass of its default methods and create a new method called getDefaultNamespace in the class to handle the task we want it to do (this method overrides the one in the Illuminate\Foundation\Console\ModelMakeCommand we are extending).

The ModelMakeClass becomes:

<?php

namespace App\Console\Commands;

use Illuminate\Foundation\Console\ModelMakeCommand as Command;

class ModelMakeCommand extends _Command_  
{

_/\*\*  
     \* Get the default namespace for the class.  
     \*  
     \*_ **_@param_** _string $rootNamespace  
     \*_ **_@return_** _string  
     \*/_ protected function getDefaultNamespace($rootNamespace)
    {
        //logic to change default behaviour
    }

}

The final thing to add to the new command class we just created is the logic to make our folder the default folder to put model files, in my case the Models folder.

The two different versions of the getDefaultNamespace methods.

Our new command class now becomes:

<?php

namespace App\Console\Commands;

use Illuminate\Foundation\Console\ModelMakeCommand as Command;

class ModelMakeCommand extends _Command_  
{
_/\*\*  
     \* Get the default namespace for the class.  
     \*  
     \*_ **_@param_** _string $rootNamespace  
     \*_ **_@return_** _string  
     \*/_ protected function getDefaultNamespace($rootNamespace)
    {
        return "{$rootNamespace}\Models";
    }
}

Finally, running the artisan command to create a new model will put the models in the app\Models folder by default 🙂.

TL;DR:

To change the default model folder in a Laravel app

Create a new artisan command with name ModelMakeCommand
Extend the Illuminate\Foundation\Console\ModelMakeCommand class instead of the Illuminate\Console\Command class.
Remove other methods and attributes from the class and then create a new method called getDefaultNamespace with content:

_/\*\*  
     \* Get the default namespace for the class.  
     \*  
     \*_ **_@param_** _string $rootNamespace  
     \*_ **_@return_** _string  
     \*/_ protected function getDefaultNamespace($rootNamespace)
    {
        return "{$rootNamespace}\Models";
    }

The full class becomes:

<?php

namespace App\Console\Commands;

use Illuminate\Foundation\Console\ModelMakeCommand as Command;

class ModelMakeCommand extends _Command_  
{
_/\*\*  
     \* Get the default namespace for the class.  
     \*  
     \*_ **_@param_** _string $rootNamespace  
     \*_ **_@return_** _string  
     \*/_ protected function getDefaultNamespace($rootNamespace)
    {
        return "{$rootNamespace}\Models";
    }
}

Run model creation artisan command and the models will be seen in the app\Models folder.

Thanks

One Laravel Form Request Class, Multiple HTTP Methods

Elisha Ukpong — Thu, 16 Jul 2020 23:36:38 +0000

Laravel comes with request validations out of the box and this makes it a whole lot easier to validate user inputs when receiving form submissions. In this short post, I will be explaining the form request class, its default methods, and how to utilize this form request to match more than one HTTP method.

Just to point out, Laravel also has a validation factory (Illuminate\Validation\Factory) class, which in my opinion, is more often used by developers than the form request class.

The validation factory class seems to be the default validation method Laravel ships out with the controller and this validation factory can be accessed in the controller without any user setup via:

$this->validate($request,$rules,$messages,$customAttributes).

The $messages and $customAttributes arrays are optional and the function can be called without them, like this:

$this->validate($request, $rules).

This method works pretty fine but when the validation logic grows, it is often advised to move it to its own class, hence the Form Request Class.

The form request class can be created using Laravel’s artisan command:

php artisan make:request RequestClassName

This command will create a Requests folder in the app\Http directory of your Laravel application and create a FormRequest Class, using the class name you passed when creating the FormRequest Class, in our case requestClassName.

To briefly explain the content of the FormRequest class, the class comes with two methods: authorize and rules.

<?php

namespace App\Http\Requests;

use Illuminate\Foundation\Http\FormRequest;

class CreateNewRequest extends FormRequest
{
_/\*\*  
     \* Determine if the user is authorized to make this request.  
     \*  
     \*_ **_@return_** _bool  
     \*/_ public function authorize()
    {
        return false;
    }

_/\*\*  
     \* Get the validation rules that apply to the request.  
     \*  
     \*_ **_@return_** _array  
     \*/_ public function rules()
    {
        return [
            //
        ];
    }
}

The authorize method checks if a user is authorized to make a request, so an example use case here can be a blogging system where only a post creator can edit his/her post. Assuming the blog post has a column user_id that tracks which user made the post, the authorize function can look like this:

_/\*\*  
 \* Determine if the user is authorized to make this request.  
 \*  
 \*_ **_@return_** _bool  
 \*/_ public function authorize()
{
   return $blogPost->user\_id === auth()->id();
}

So this returns true and then moves to process the edit request only when the blog post edit request is made by the blog post owner, else it will return false and throw an exception back to the user, moving to the next method.

The rules method contains the validation logic of any form that utilizes the FormRequest class.

The FormRequest class can be injected into any method in which you want the FormRequest validation logic to hold true, and this cleans up your controller.

Having explained the concepts surrounding the readily available validate method and the user-created form request class, let me move to the main problem that this post aims to shed light on.

Ideally, creating and updating a model’s record might require differing validations for the model’s column, to make an example, let us continue using the blog analogy.

To create a blog, we might decide that an image is required, the blog post name is required, same as the blog post content, but on updating the post, the blog post image would necessarily not be required, it becomes an optional validation.

_/\*\*  
 \* Get the validation rules that apply to the request.  
 \*  
 \*_ **_@return_** _array  
 \*/_ public function rules()
{
    //blog post creation rules

    return [
        'name' => 'string | required',
        'content' => 'string | required',
        'image' => 'image | required'
    ];
}

_/\*\*  
 \* Get the validation rules that apply to the request.  
 \*  
 \*_ **_@return_** _array  
 \*/_ public function rules()
{
    //blog post update rules

    return [
        'name' => 'string | required',
        'content' => 'string | required',
        'image' => 'image'
    ];
}

The above two rules are different and if I want to stick to the Form Request class way of validation I might have to make more form requests classes should I have differing validation logic for POST, PUT, PATCH and DELETE. To solve this with only one form class, it is possible to edit the form request to make it more versatile such that it serves different rules for different HTTP verbs. See code sample below:

protected $rules = [

];

_/\*\*  
 \* Get the validation rules that apply to the request.  
 \*  
 \*_ **_@return_** _array  
 \*/_ public function rules()
{
    $method = $this->method();
    if (null !== $this->get('\_method', null)) {
        $method = $this->get('\_method');
    }
    $this->offsetUnset('\_method');
    switch ($method) {
        case 'DELETE':
        case 'GET':
                $this->rules = [];
            break;

        case 'POST':

            break;
        // in case of edit
        case 'PUT':
        case 'PATCH':

            break;
        default:
            break;
    }

    return $this->rules;
}

Explanation:

$method = $this->method();

The code snippet above retrieves the HTTP method from the request object and stores it to a variable, $method, next.

if (null !== $this->get('\_method', null)) {
        $method = $this->get('\_method');
    }

Knowing that Laravel has a way of masking or changing the original request method using the @method() directive, the code tests to see if a method is specified in the request object, if it is, then it updates the method variable with it.

$this->offsetUnset('\_method');

This removes the “_method” attribute from the request object, and as such we have realized the type of HTTP request that is been sent to our application and can then serve differing rules for each request type.

switch ($method) {
        case 'DELETE':
                $this->rules = [//rules here for delete request];
            break;

        case 'GET':
                $this->rules = [//rules here for get request];
            break;

        case 'POST':
               $this->rules = [//rules here for post request];
            break;

        case 'PUT':
               $this->rules = [//rules here for put request];
            break;   

        case 'PATCH':
               $this->rules = [//rules here for patch request];
            break;

        default:
            break;
    }

    return $this->rules;

The above switch statement updates the rules array with appropriate validation logic for each request type and helps you have them all in one request class.

Thank you for reading until the end 🙂