Laravel Eventual Package is the Newly released Package for Actions and Filters Management system through Laravel Framework and PHP

Concept

In this Guide we will take a general overview about how this package work and basic concepts to get more familiar when working with Eventual Package.

The main purpose of this Package is to add the ability for the developer to inject code and logic pieces in a clean and standalone way, which will lead to better decoupling. Concept is inspired by WordPress Hooks System which allows developers to execute code on certain events and also filters data passing through application without touching the core code.

Filters vs Actions

We will use those terms a lot in from now on so you need to have a clear understanding of how they work and defer from each others

Actions : can be considered as an event that happens in some certain situations and may need further sequential actions to be taken upon that event, so for example consider saving a new blog post (Action), then you can inject a piece of code (Handler) to send an email to subscribers afterwards.

Filters : Actually it’s a piece of data that been collected or manipulated by the application and may need to be altered or filtered, lets say for example in our application we returning a list of blog posts in order to show it to our visitors, in this case we may want to filter this posts and exclude a private ones before returning them to the visitor

Installation

First make sure you have composer installed first, but in case you already working with laravel then likely you’ll have it installed already.

Open your terminal and CD in your laravel project root

Run the following composer command to install the package

composer require codersamer/eventual

Once installed you can start using this package.

Note : if you have a laravel project with version less than 6, then you’ll need to add the corresponding service provider to your application

Add Service Provider (Laravel Below 6)

Go to your config/app.php file and open it with your preferred code editor and add the following provider to the “providers” array

Codersamer\Eventual\Providers\EventualServiceProvider

Basic Usage

Eventual Package depends mainly on four methods doAction, onAction, doFilter, onFilter. The “do” part means fire or apply and find the all registered handlers for that event or filter which the “on” part means when that thing happens run the following piece of code accordingly .

At the very basic Level we can use this methods on the Eventual Facade

Codersamer\Eventual\Facades\Eventual

Register an Action

Before Handling an action we need to know how we fire or tell laravel that some action happening now and need to take further actions afterwards. This can be achieved simply by calling the method doAction like so

<?php
using Codersamer\Eventual\Facades\Eventual;
//....
Eventual::doAction('blog_post_saved', $argument1, $argument2);

First parameter indicates the action name that all handlers should use to respond to this action, other arguments indicates the data that will be carried to all handlers.

Note : Arguments are not limited to some number, you can pass as many arguments as you need and all of them will be carried to handlers, also it support all types of data so it can be primitive type, model, custom object … etc

Handle an Action Now our application fires events and actions in some points of app life cycle, it’s the time for us to learn how to handle this actions and act accordingly which can be achieved by called the method onAction as following

<?php
using Codersamer\Eventual\Facades\Eventual;
//....
Eventual::onAction('blog_post_saved', function($argument1, $argument2){
    //Act to the Action
    //Send some email to subscribers
});

This piece of code tells Eventual Package to take some steps / run piece of code only when some action occurred, in this case it’s “blog_post_saved“, and as we mentioned before all handlers will receive the corresponding arguments been sent via the dispatcher

Register a Filter As we registered an action before we can also register a filter before handle it later using the method doFilter , this way we can later modify that piece of data in any point of the application

<?php
using Codersamer\Eventual\Facades\Eventual;
//....
$post = Eventual::doFilter('posts_list', $posts, $extraArgument);

As you may notice here we could pass more than one argument to be carried on to the handlers / filters, but keep in mind that the filters system will only look for updates happen on the first argument, in this case “$posts”, also it returns the first argument again after been modified by all handlers added to this filter, so consider the extra arguments are just a reference information regarding this filter but actually the filters system doesn’t really care about it.

Handle a Filter

In the Previous part we learned how to register a filter, now it’s the time to add handlers for this filter, it’s some how identical to how to handle actions but with some key differences

<?php
using Codersamer\Eventual\Facades\Eventual;
....
Eventual::onFilter('posts_list', function($posts, $extraArguments = null){
    //Add Updates to the posts if needed, then return it
    return $posts;
});

As you can see it’s very similar to handling actions but the key difference here is that you MUST return the first argument again after your modifications as the dispatcher now waiting for it.

Conclusion

Working with Filters and Actions Pattern is very fun and helps with code decoupling, so you can modify application core logic and manipulate data without touching the core code which may be useful when developing a modular laravel application, multi-theme system, multi-plugins system.

Now let me tell you that you are now familiar and capable of working with this package but this is not all, we have more advanced features and techniques to discuss later, so keep reading and exploring.

Coder Sam