Sections

Events Manager


Genel Bakış

The purpose of this component is to intercept the execution of components in the framework by creating hooks. These hooks allow developers to obtain status information, manipulate data or change the flow of execution during the process of a component. The component consists of a Phalcon\Events\Manager that handles event propagation and execution of events. The manager contains various Phalcon\Events\Event objects, which contain information about each hook/event.

<?php

use Phalcon\Events\Event;
use Phalcon\Events\Manager as EventsManager;
use Phalcon\Db\Adapter\Pdo\Mysql as DbAdapter;

$eventsManager = new EventsManager();

$eventsManager->attach(
    'db:afterQuery',
    function (Event $event, $connection) {
        echo $connection->getSQLStatement();
    }
);

$connection = new DbAdapter(
    [
        'host'     => 'localhost',
        'username' => 'root',
        'password' => 'secret',
        'dbname'   => 'invo',
    ]
);

$connection->setEventsManager($eventsManager);
$connection->query(
    'SELECT * FROM products p WHERE p.status = 1'
);

Naming Convention

Phalcon events use namespaces to avoid naming collisions. Each component in Phalcon occupies a different event namespace and you are free to create your own as you see fit. Event names are formatted as component:event. For example, as Phalcon\Db occupies the db namespace, its afterQuery event’s full name is db:afterQuery.

When attaching event listeners to the events manager, you can use component to catch all events from that component (eg. db to catch all of the Phalcon\Db events) or component:event to target a specific event (eg. db:afterQuery).

Manager

The Phalcon\Events\Manager is the main component that handles all the events in Phalcon. Different implementations in other frameworks refer to this component as a handler. Regardless of the name, the functionality and purpose are the same.

The component wraps a queue of objects using SplPriorityQueue internally. It registers those objects with a priority (default 100) and then when the time comes, executes them.

The methods exposed by the manager are:

public function attach(
    string $eventType, 
    mixed $handler, 
    int $priority = self::DEFAULT_PRIORITY
)

Attaches a listener to the events manager. The handler is an object or a callable.

public function arePrioritiesEnabled(): bool

Returns if priorities are enabled

public function collectResponses(bool $collect)

Tells the event manager if it needs to collect all the responses returned by every registered listener in a single fire call

public function detach(string $eventType, mixed $handler)

Detach the listener from the events manager

public function detachAll(string $type = null)

Removes all events from the EventsManager

public function enablePriorities(bool $enablePriorities)

Set if priorities are enabled in the events manager (default false).

public function fire(string $eventType, mixed $source, mixed $data = null, bool $cancelable = true)

Fires an event in the events manager causing the active listeners to be notified about it

final public function fireQueue(SplPriorityQueue $queue, EventInterface $event): mixed

Internal handler to call a queue of events

public function getListeners(string $type): array

Returns all the attached listeners of a certain type

public function getResponses(): array

Returns all the responses returned by every handler executed by the last fire executed

public function hasListeners(string $type): bool

Check whether certain type of event has listeners

public function isCollecting(): bool

Check if the events manager is collecting all all the responses returned by every registered listener in a single fire

Kullanım

If you are using the Phalcon\Di\FactoryDefault DI container, the Phalcon\Events\Manager is already registered for you with the name eventsManager. This is a global events manager. However you are not restricted to use only that one. You can always create a separate manager to handle events for any component that you require.

The following example shows how you can create a query logging mechanism using the global events manager:

<?php

use Phalcon\Di\FactoryDefault;
use Phalcon\Events\Event;
use Phalcon\Db\Adapter\Pdo\Mysql as DbAdapter;

$container     = Di::getDefault();
$eventsManager = $container->get('eventsManager');

$eventsManager->attach(
    'db:afterQuery',
    function (Event $event, $connection) {
        echo $connection->getSQLStatement();
    }
);

$connection = new DbAdapter(
    [
        'host'     => 'localhost',
        'username' => 'root',
        'password' => 'secret',
        'dbname'   => 'invo',
    ]
);

$connection->setEventsManager($eventsManager);
$connection->query(
    'SELECT * FROM products p WHERE p.status = 1'
);

or if you want a separate events manager:

<?php

use Phalcon\Events\Event;
use Phalcon\Events\Manager as EventsManager;
use Phalcon\Db\Adapter\Pdo\Mysql as DbAdapter;

$eventsManager = new EventsManager();
$eventsManager->attach(
    'db:afterQuery',
    function (Event $event, $connection) {
        echo $connection->getSQLStatement();
    }
);

$connection = new DbAdapter(
    [
        'host'     => 'localhost',
        'username' => 'root',
        'password' => 'secret',
        'dbname'   => 'invo',
    ]
);

$connection->setEventsManager($eventsManager);
$connection->query(
    'SELECT * FROM products p WHERE p.status = 1'
);

In the above example, we are using the events manager to listen to the afterQuery event produced by the db service, in this case MySQL. We use the attach method to attach our event to the manager and use the db:afterQuery event. We add an anonymous function as the handler for this event, which accepts a Phalcon\Events\Event as the first parameter. This object contains contextual information regarding the event that has been fired. The database connection object as the second. Using the connection variable we print out the SQL statement. You can always pass a third parameter with arbitrary data specific to the event, or even a logger object in the anonymous function so that you can log your queries in a separate log file.

NOTE: You must explicitly set the Events Manager to a component using the setEventsManager() method in order for that component to trigger events. You can create a new Events Manager instance for each component or you can set the same Events Manager to multiple components as the naming convention will avoid conflicts

İşleyiciler

The events manager wires a handler to an event. A handler is a piece of code that will do something when the event fires. As seen in the above example, you can use an anonymous function as your handler:

<?php

use Phalcon\Events\Event;
use Phalcon\Events\Manager as EventsManager;
use Phalcon\Db\Adapter\Pdo\Mysql as DbAdapter;

$eventsManager = new EventsManager();
$eventsManager->attach(
    'db:afterQuery',
    function (Event $event, $connection) {
        echo $connection->getSQLStatement();
    }
);

$connection = new DbAdapter(
    [
        'host'     => 'localhost',
        'username' => 'root',
        'password' => 'secret',
        'dbname'   => 'invo',
    ]
);

$connection->setEventsManager($eventsManager);
$connection->query(
    'SELECT * FROM products p WHERE p.status = 1'
);

You can also create a listener class, which offers more flexibility. In a listener, you can listen to multiple events and even extend [Phalcon\Di\Injectable][di-injectable] which will give you fill access to the services of the Di container. The example above can be enhanced by implementing the following listener:

<?php

namespace MyApp\Listeners;

use Phalcon\Logger;
use Phalcon\Config;
use Phalcon\Db\AdapterInterface;
use Phalcon\Di\Injectable;
use Phalcon\Events\Event;

/**
 * Class QueryListener
 *
 * @property Config $config
 * @property Logger $logger
 */
class QueryListener extends Injectable
{
    public function beforeQuery(Event $event, AdapterInterface $connection)
    {
        if ($this->config->path('app.logLevel') > 1) {
            $this->logger->info(
                sprintf(
                    '%s - [%s]',
                    $connection->getSQLStatement(),
                    json_encode($connection->getSQLVariables())
                )
            );
        }
    }

    public function rollbackTransaction(Event $event)
    {
        if ($this->config->path('app.logLevel') > 1) {
            $this->logger->warning($event->getType());
        }
    }
}

Attaching the listener to our events manager is very simple:

<?php

$eventsManager->attach(
    'db',
    new QueryListener()
);

The resulting behavior will be that if the app.logLevel configuration variable is set to greater than 1 (representing that we are in development mode), all queries will be logged along with the actual parameters that were bound to each query. Additionally we will log every time we have a rollback in a transaction.

Another handy listener is the 404 one:

<?php

namespace MyApp\Listeners\Dispatcher;

use Phalcon\Logger;
use Phalcon\Di\Injectable;
use Phalcon\Events\Event;
use Phalcon\Mvc\Dispatcher;
use MyApp\Auth\Adapters\AbstractAdapter;

/**
 * Class NotFoundListener
 *
 * @property AbstractAdapter $auth
 * @property Logger          $logger
 */
class NotFoundListener extends Injectable
{
    public function beforeException(
        Event $event, 
        Dispatcher $dispatcher, 
        \Exception $ex
    ) {
        switch ($ex->getCode()) {
            case Dispatcher::EXCEPTION_HANDLER_NOT_FOUND:
            case Dispatcher::EXCEPTION_ACTION_NOT_FOUND:
                $dispatcher->setModuleName('main');
                $params = [
                    'namespace'  => 'MyApp\Controllers',
                    'controller' => 'session',
                    'action'     => 'fourohfour',
                ];

                /**
                 * 404 not logged in
                 */
                if (true !== $this->auth->isLoggedIn()) {
                    $params['action'] = 'login';
                }

                $dispatcher->forward($params);

                return false;
            default:
                $this->logger->error($ex->getMessage());
                $this->logger->error($ex->getTraceAsString());

                return false;
        }
    }
}

and attaching it to the events manager:

<?php

$eventsManager->attach(
    'dispatch:beforeException',
    new NotFoundListener(),
    200
);

First we attach the listener to the dispatcher component and the beforeException event. This means that the events manager will fire only for that event calling our listener. We could have just changed the hook point to dispatcher so that we are able in the future to add more dispatcher events in the same listener.

The beforeException function accepts the $event as the first parameter, the $dispatcher as the second and the $ex exception thrown from the dispatcher component. Using those, we can then figure out if a handler (or controller) or an action were not found. If that is the case, we forward the user to a specific module, controller and action. If our user is not logged in, then we send them to the login page. Alternatively, we just log the exception message in our logger.

The example demonstrates clearly the power of the events manager, and how you can alter the flow of the application using listeners.

Events: Trigger

You can create components in your application that trigger events to an events manager. Listeners attached to those events will be invoked when the events are fired. In order to create a component that triggers events, we need to implement the Phalcon\Events\EventsAwareInterface.

Custom Component

Let’s consider the following example:

<?php

namespace MyApp\Components;

use Phalcon\Di\Injectable;
use Phalcon\Events\EventsAwareInterface;
use Phalcon\Events\ManagerInterface;

/**
 * @property Logger $logger
 */
class NotificationsAware extends Injectable implements EventsAwareInterface
{
    protected $eventsManager;

    public function getEventsManager()
    {
        return $this->eventsManager;
    }

    public function setEventsManager(ManagerInterface $eventsManager)
    {
        $this->eventsManager = $eventsManager;
    }


    public function process()
    {
        $this->eventsManager->fire('notifications:beforeSend', $this);

        $this->logger->info('Processing.... ');

        $this->eventsManager->fire('notifications:afterSend', $this);
    }
}

The above component implements the Phalcon\Events\EventsAwareInterface and as a result it uses the getEventsManager and setEventsManager. The last method is what does the work. In this example we want to send some notifications to users and want to fire an event before and after the notification is sent.

We chose to name the component notification and the events are called beforeSend and afterSend. In the process method, you can add any code you need in between the calls to fire the relevant events. Additionally, you can inject more data in this component that would help with your implementation and processing of the notifications.

Custom Listener

Now we need to create a listener for this component:

<?php

namespace MyApp\Listeners;

use Phalcon\Events\Event;
use Phalcon\Logger;

/**
 * @property Logger $logger
 */
class MotificationsListener
{
    /**
     * @var Logger
     */
    private $logger;

    public function __construct(Logger $logger)
    {
        $this->logger = $logger;
    }

    public function afterSend(
        Event $event, 
        NotificationsAware $component
    ) {
        $this->logger->info('After Notification');
    }

    public function beforeSend(
        Event $event, 
        NotificationsAware $component
    ) {
        $this->logger->info('Before Notification');
    }
}

Putting it all together

<?php

use MyApp\Components\NotificationAware;
use MyApp\Listeners\MotificationsListener;
use Phalcon\Events\Manager as EventsManager;

$eventsManager = new EventsManager();
$component     = new NotificationAware();

$component->setEventsManager($eventsManager);

$eventsManager->attach(
    'notifications',
    new NotificationsListener()
);

$component->process();

When process is executed, the two methods in the listener will be executed. Your log will then have the following entries:

[2019-12-25 01:02:03][INFO] Before Notification
[2019-12-25 01:02:03][INFO] Processing...
[2019-12-25 01:02:03][INFO] After Notification

Custom Data

Additional data may also be passed when triggering an event using the third parameter of fire():

<?php

$data = [
    'name'     => 'Darth Vader',
    'password' => '12345',
];

$eventsManager->fire('notifications:afterSend', $this, $data);

In a listener the third parameter also receives data:

<?php

use Phalcon\Events\Event;

$data = [
    'name'     => 'Darth Vader',
    'password' => '12345',
];

$eventsManager->attach(
    'notifications',
    function (Event $event, $component, $data) {
        print_r($data);
    }
);

$eventsManager->attach(
    'notifications',
    function (Event $event, $component) {
        print_r($event->getData());
    }
);

Propagation

An events manager can have multiple listeners attached to it. Once an event fires, all listeners that can be notified for the particular event will be notified. This is the default behavior but can be altered if need be by stopping the propagation early:

<?php

use Phalcon\Events\Event;

$eventsManager->attach(
    'db',
    function (Event $event, $connection) {
        if ('2019-01-01' < date('Y-m-d')) {
            $event->stop();
        }
    }
);

In the above simple example, we stop all events if today is earlier than 2019-01-01.

Cancellation

By default all events are cancelable. However you might want to set a particular event to not be cancelable, allowing the particular event to fire on all available listeners that implement it.

<?php

use Phalcon\Events\Event;

$eventsManager->attach(
    'db',
    function (Event $event, $connection) {
        if ($event->isCancelable()) {
            $event->stop();
        }
    }
);

In the above example, if the event is cancelable, we will stop propagation. You can set a particular event to not be cancelable by utilizing the fourth parameter of fire():

<?php

$eventsManager->fire('notifications:afterSend', $this, $data, false);

The afterSend event will no longer be cancelable and will execute on all listeners that implement it.

NOTE: You can stop the execution by returning false in your event (but not always). For instance, if you attach an event to dispatch:beforeDispatchLoop and your listener returns false the dispatch process will be halted. This is true if you only have one listener listening to the dispatch:beforeDispatchLoop event which returns false. If two listeners are attached to the event and the second one that executes returns true then the process will continue. If you wish to stop any subsequent events from firing, you will have to issue a stop() in your listener on the Event object.

Priorities

When attaching listeners you can set a specific priority. Setting up priorities when attaching listeners to your events manager defines the order in which they are called:

<?php

use Phalcon\Events\Manager as EventsManager;

$eventsManager = new EventsManager();

$eventsManager->enablePriorities(true);

$eventsManager->attach(
    'db', 
    new QueryListener(), 
    150
);
$eventsManager->attach(
    'db', 
    new QueryListener(), 
    100
);
$eventsManager->attach(
    'db', 
    new QueryListener(), 
    50
); 

NOTE: In order for the priorities to work enablePriorities() has to be called with true so as to enable them. Priorities are disabled by default

NOTE: A high priority number means that the listener will be processed before those with lower priorities

Yanıtlar

The events manager can also collect any responses returned by each event and return them back using the getResponses() method. The method returns an array with the responses:

<?php

use Phalcon\Events\Manager as EventsManager;

$eventsManager = new EventsManager();

$eventsManager->collectResponses(true);

$eventsManager->attach(
    'custom:custom',
    function () {
        return 'first response';
    }
);

$eventsManager->attach(
    'custom:custom',
    function () {
        return 'second response';
    }
);

$eventsManager->fire('custom:custom', null);

print_r($eventsManager->getResponses());

The above example produces:

[
    0 => 'first response',
    1 => 'second response',
]

NOTE: In order for the priorities to work collectResponses() has to be called with true so as to enable collecting them.

Exceptions

Any exceptions thrown in the Paginator component will be of type Phalcon\Events\Exception. You can use this exception to selectively catch exceptions thrown only from this component.

<?php

use Phalcon\Events\EventsManager;
use Phalcon\Events\Exception;

try {

    $eventsManager = new EventsManager();

    $eventsManager->attach('custom:custom', true);
} catch (Exception $ex) {
    echo $ex->getMessage();
}

Controllers

Controllers act as listeners already registered in the events manager. As a result, you only need to create a method with the same name as a registered event and it will be fired.

For instance if we want to send a user to the /login page if they are not logged in, we can add the following code in our master controller:

<?php

namespace MyApp\Controller;

use Phalcon\Logger;
use Phalcon\Dispatcher;
use Phalcon\Http\Response;
use Phalcon\Mvc\Controller;
use MyApp\Auth\Adapters\AbstractAdapter;

/**
 * Class BaseController
 *
 * @property AbstractAdapter $auth
 * @property Logger          $logger
 * @property Response        $response
 */
class BaseController extends Controller
{
    public function beforeExecuteRoute(Dispatcher $dispatcher)
    {
        /**
         * Send them to the login page if no identity exists
         */
        if (true !== $this->auth->isLoggedIn()) {
            $this->response->redirect(
                '/login',
                true
            );

            return false;
        }

        return true;
    }
}

Execute the code before the router so we can determine if the user is logged in or not. If not, forward them to the login page.

Models

Similar to Controllers, Models also act as listeners already registered in the events manager. As a result, you only need to create a method with the same name as a registered event and it will be fired.

In the following example, we are use the beforeCreate event, to automatically calculate an invoice number:

<?php

namespace MyApp\Models;

use Phalcon\Mvc\Model;use function str_pad;

/**
 * Class Invoices
 *
 * @property string $inv_created_at
 * @property int    $inv_cst_id
 * @property int    $inv_id
 * @property string $inv_number
 * @property string $inv_title
 * @property float  $inv_total
 */
class Invoices extends Model
{
    /**
     * @var int
     */
    public $inv_cst_id;

    /**
     * @var string
     */
    public $inv_created_at;

    /**
     * @var int
     */
    public $inv_id;

    /**
     * @var string
     */
    public $inv_number;

    /**
     * @var string
     */
    public $inv_title;

    /**
     * @var float
     */
    public $inv_total;

    public function beforeCreate()
    {
        $date     = date('YmdHis');
        $customer = substr(
            str_pad(
                $this->inv_cst_id, 6, '0', STR_PAD_LEFT
            ),
            -6
        );

        $this->inv_number = 'INV-' . $customer . '-' . $date;
    }
}

Custom

The Phalcon\Events\ManagerInterface interface must be implemented to create your own events manager replacing the one provided by Phalcon.

<?php

namespace MyApp\Events;

use Phalcon\Events\ManagerInterface;

class EventsManager implements ManagerInterface
{
    /**
     * Attach a listener to the events manager
     *
     * @param string          $eventType
     * @param object|callable $handler
     */
    public function attach(string $eventType, $handler);

    /**
     * Detach the listener from the events manager
     *
     * @param string          $eventType
     * @param object|callable $handler
     */
    public function detach(string $eventType, $handler);

    /**
     * Removes all events from the EventsManager
     * 
     * @param string $type
     */
    public function detachAll(string $type = null);

    /**
     * Fires an event in the events manager causing the active 
     * listeners to be notified about it
     *
     * @param string $eventType
     * @param object $source
     * @param mixed  $data
     * @param mixed  $cancelable
     * 
     * @return mixed
     */
    public function fire(
        string $eventType, 
        $source, 
        $data = null, 
        bool $cancelable = false
    );

    /**
     * Returns all the attached listeners of a certain type
     *
     * @param string $type
     *
     * @return array
     */
    public function getListeners(string $type): array;

    /**
     * Check whether certain type of event has listeners
     *
     * @param string $type
     *
     * @return bool
     */
    public function hasListeners(string $type): bool;
}

List of Events

The events available in Phalcon are:

Component Event Parametreler  
ACL acl:afterCheckAccess Acl  
ACL acl:beforeCheckAccess Acl  
Uygulama application:afterHandleRequest Application, Controller  
Uygulama application:afterStartModule Application, Module  
Uygulama application:beforeHandleRequest Application, Dispatcher  
Uygulama application:beforeSendResponse Application, Response  
Uygulama application:beforeStartModule Application, Module  
Uygulama application:boot Uygulama  
Uygulama application:viewRender Application, View  
CLI dispatch:beforeException Console, Exception  
Console console:afterHandleTask Console, Task  
Console console:afterStartModule Console, Module  
Console console:beforeHandleTask Console, Dispatcher  
Console console:beforeStartModule Console, Module  
Console console:boot Console  
Db db:afterQuery Db  
Db db:beforeQuery Db  
Db db:beginTransaction Db  
Db db:createSavepoint Db, Savepoint Name  
Db db:commitTransaction Db  
Db db:releaseSavepoint Db, Savepoint Name  
Db db:rollbackTransaction Db  
Db db:rollbackSavepoint Db, Savepoint Name  
Gönderici dispatch:afterExecuteRoute Gönderici  
Gönderici dispatch:afterDispatch Gönderici  
Gönderici dispatch:afterDispatchLoop Gönderici  
Gönderici dispatch:afterInitialize Gönderici  
Gönderici dispatch:beforeException Dispatcher, Exception  
Gönderici dispatch:beforeExecuteRoute Gönderici  
Gönderici dispatch:beforeDispatch Gönderici  
Gönderici dispatch:beforeDispatchLoop Gönderici  
Gönderici dispatch:beforeForward Dispatcher, array  
Gönderici dispatch:beforeNotFoundAction Dispatcher  
Yükleyici loader:afterCheckClass Loader, Class Name  
Yükleyici loader:beforeCheckClass Loader, Class Name  
Yükleyici loader:beforeCheckPath Yükleyici  
Yükleyici loader:pathFound Loader, File Path  
Minik micro:afterBinding Minik  
Minik micro:afterHandleRoute Micro, return value mixed  
Minik micro:afterExecuteRoute Minik  
Minik micro:beforeException Micro, Exception  
Minik micro:beforeExecuteRoute Minik  
Minik micro:beforeHandleRoute Minik  
Minik micro:beforeNotFound Minik  
Model model:afterCreate Model  
Model model:afterDelete Model  
Model model:afterFetch Model  
Model model:afterSave Model  
Model model:afterUpdate Model  
Model model:afterValidation Model  
Model model:afterValidationOnCreate Model  
Model model:afterValidationOnUpdate Model  
Model model:beforeDelete Model  
Model model:beforeCreate Model  
Model model:beforeSave Model  
Model model:beforeUpdate Model  
Model model:beforeValidation Model  
Model model:beforeValidationOnCreate Model  
Model model:beforeValidationOnUpdate Model  
Model model:notDeleted Model  
Model model:notSaved Model  
Model model:onValidationFails Model  
Model model:prepareSave Model  
Model model:validation Model  
Models Manager modelsManager:afterInitialize Manager, Model  
İstek request:afterAuthorizationResolve Request, [‘server’ => Server array]  
İstek request:beforeAuthorizationResolve Request, [‘headers’ => [Headers], ‘server’ => [Server]]  
Tepki response:afterSendHeaders Tepki  
Tepki response:beforeSendHeaders Tepki  
Router router:afterCheckRoutes Router  
Router router:beforeCheckRoutes Router  
Router router:beforeCheckRoute Router, Route  
Router router:beforeMount Router, Group  
Router router:matchedRoute Router, Route  
Router router:notMatchedRoute Router, Route  
View view:afterCompile Volt  
View view:afterRender View  
View view:afterRenderView View  
View view:beforeCompile Volt  
View view:beforeRender View  
View view:beforeRenderView View, View Engine Path  
View view:notFoundView View, View Engine Path  
Volt compileFilter Volt, [name, arguments, function arguments]  
Volt compileFunction Volt, [name, arguments, function arguments]  
Volt compileStatement Volt, [statement]  
Volt resolveExpression Volt, [expression]