Events Manager¶
Overview¶
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 (e.g. db to catch all 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:
Attaches a listener to the events manager. Thehandler is an object or a callable. Returns if priorities are enabled Tell the event manager if it needs to collect all the responses returned by every registered listener in a single fire call Detach the listener from the events manager Removes all events from the EventsManager Set if priorities are enabled in the events manager (default false). 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
```php
public function getListeners(string $type): array
fire executed Check whether a certain type of event has listeners Check if the events manager is collecting all the responses returned by every registered listener in a single fire Check if the handler is an object or a callable Usage¶
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
Handlers¶
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:
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:
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 was 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 ManagerInterface $eventsManager
* @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():
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 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
Responses¶
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', $eventsManager, null);
print_r($eventsManager->getResponses());
The above example produces:
NOTE
In order for the priorities to work collectResponses() has to be called with true 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;
}
}
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 using 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
{
/**
* @param string $eventType
* @param object|callable $handler
*/
public function attach(string $eventType, $handler);
/**
* @param string $eventType
* @param object|callable $handler
*/
public function detach(string $eventType, $handler);
/**
* @param string $type
*/
public function detachAll(string $type = null);
/**
* @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
);
/**
* @param string $type
*
* @return array
*/
public function getListeners(string $type): array;
/**
* @param string $type
*
* @return bool
*/
public function hasListeners(string $type): bool;
}
List of Events¶
The events available in Phalcon are:
| Component | Event | Parameters |
|---|---|---|
| ACL | acl:afterCheckAccess | Acl |
| ACL | acl:beforeCheckAccess | Acl |
| Application | application:afterHandleRequest | Application, Controller |
| Application | application:afterStartModule | Application, Module |
| Application | application:beforeHandleRequest | Application, Dispatcher |
| Application | application:beforeSendResponse | Application, Response |
| Application | application:beforeStartModule | Application, Module |
| Application | application:boot | Application |
| Application | 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 |
| Dispatcher | dispatch:afterBinding | Dispatcher |
| Dispatcher | dispatch:afterDispatch | Dispatcher |
| Dispatcher | dispatch:afterDispatchLoop | Dispatcher |
| Dispatcher | dispatch:afterExecuteRoute | Dispatcher |
| Dispatcher | dispatch:afterInitialize | Dispatcher |
| Dispatcher | dispatch:beforeDispatch | Dispatcher |
| Dispatcher | dispatch:beforeDispatchLoop | Dispatcher |
| Dispatcher | dispatch:beforeException | Dispatcher, Exception |
| Dispatcher | dispatch:beforeExecuteRoute | Dispatcher |
| Dispatcher | dispatch:beforeForward | Dispatcher, array (MVC Dispatcher) |
| Dispatcher | dispatch:beforeNotFoundAction | Dispatcher |
| Loader | loader:afterCheckClass | Loader, Class Name |
| Loader | loader:beforeCheckClass | Loader, Class Name |
| Loader | loader:beforeCheckPath | Loader |
| Loader | loader:pathFound | Loader, File Path |
| Micro | micro:afterBinding | Micro |
| Micro | micro:afterHandleRoute | Micro, return value mixed |
| Micro | micro:afterExecuteRoute | Micro |
| Micro | micro:beforeException | Micro, Exception |
| Micro | micro:beforeExecuteRoute | Micro |
| Micro | micro:beforeHandleRoute | Micro |
| Micro | micro:beforeNotFound | Micro |
| 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 |
| Request | request:afterAuthorizationResolve | Request, ['server' => Server array] |
| Request | request:beforeAuthorizationResolve | Request, ['headers' => [Headers], 'server' => [Server]] |
| Response | response:afterSendHeaders | Response |
| Response | response:beforeSendHeaders | Response |
| 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] |