Note |
---|
|
As of version 4.3.0 the event system has been updated. To see the old deprecated method of using events look at the "Creating Events (Old)" section below |
Creating an event simply sets a callback to be invoked if and only if during the execution of the current program such an event is triggered. This is useful if you require notification of certain actions throughout your application.
Registering an Event
Before registering you will need to build a Listener to register the event with.
Code Block |
---|
language | php |
---|
title | Building an event listener |
---|
|
$eventFactory = $this->getFromContainer('util.events');
$eventListener = $eventFactory->listener(); |
Note |
---|
|
The method getFromContainer() is part of the Blesta\Core\Util\Common\Container trait and is available in any controllers or models the inherit from AppController or AppModel. If you are working in a location that does not inherit from either you can gain access to the method by applying the Container trait to your class. |
Registering an event will allow your callback to be notified when such an event is triggered.
Code Block |
---|
language | php |
---|
title | Your model or controller |
---|
|
$eventListener->register('EventName', [$this, 'callbackMethod']); |
In the above example, when the "EventName" event is triggered the "callbackMethod" will be invoked on the object that registered the event.
Note |
---|
title | An event can be registered more than once |
---|
|
If you register the same event with the same callback more than once that callback will be executed multiple times each time the event is triggered. |
Triggering an Event
Triggering an event invokes all callbacks that have been registered for that event. To trigger the "EventName" event invoke Listener's trigger method and pass in an Event that will be passed to each callback.
Code Block |
---|
language | php |
---|
title | Somewhere in your code |
---|
|
$eventListener->trigger(
$eventFactory->event('EventName', ['square', 'pink'])
); |
Here's a complete example that will output "square pink".
Code Block |
---|
language | php |
---|
firstline | 1 |
---|
title | /app/controllers/my_controller.php |
---|
linenumbers | true |
---|
|
<?php
class MyController extends AppController {
public function index()
{
$eventFactory = $this->getFromContainer('util.events');
$eventListener = $eventFactory->listener();
$eventListener->register('EventName', [$this, 'callbackMethod']);
$eventListener->trigger($eventFactory->event('EventName', ['square', 'pink']));
return false; // don't render a view
}
public function callbackMethod($event)
{
$params = $event->getParams();
echo $params[0] . " " . $params[1];
}
}
?> |
Returning Data From an Event
The Event passed to each event callback contains setters and getters for both parameters (as seen above when Triggering an Event) and return values. Expanding on the example above, we can set our return value using the Event::setReturnValue() method. This will output "square".
Code Block |
---|
language | php |
---|
firstline | 1 |
---|
title | /app/controllers/my_controller.php |
---|
linenumbers | true |
---|
|
<?php
class MyController extends AppController {
public function index()
{
$eventFactory = $this->getFromContainer('util.events');
$eventListener = $eventFactory->listener();
$eventListener->register('EventName', [$this, 'callbackMethod']);
$eventListener->trigger($eventFactory->event('EventName', ['square', 'pink']));
echo $event->getReturnValue();
return false; // don't render a view
}
public function callbackMethod($event)
{
$params = $event->getParams();
$event->setReturnValue($params[0]);
}
}
?> |
Creating Events (Old)
Creating an event simply sets a callback to be invoked if and only if during the execution of the current program such an event is triggered. This is useful if you require notification of certain actions throughout your application.
Registering an Event
Registering an event will allow your callback to be notified when such an event is triggered. Any controller or model that inherits from AppController or AppModel will already have access to the event handler and can immediately begin registering events.
...
Note |
---|
title | An event can be registered more than once |
---|
|
If you register the same event with the same callback more than once that callback will be executed multiple times each time the event is triggered. |
Triggering an Event
Triggering an event invokes all callbacks that have been registered for that event. To trigger the "EventName" event invoke the Events::trigger() method and pass in an instance of the EventObject that will be passed to each callback.
...
Here's a complete example that will output "square pink".
Code Block |
---|
language | php |
---|
firstline | 1 |
---|
title | /app/controllers/my_controller.php |
---|
firstline | 1 |
---|
linenumbers | true |
---|
|
<?php
class MyController extends AppController {
public function index() {
$this->Events->register("EventName", array($this, "callbackMethod"));
$event = new EventObject("EventName", array("square", "pink"));
$this->Events->trigger($event);
return false; // don't render a view
}
public function callbackMethod(EventObject $event) {
$params = $event->getParams();
echo $params[0] . " " . $params[1];
}
}
?> |
Returning Data From an Event
The EventObject passed to each event callback contains setters and getters for both parameters (as seen above when Triggering an Event), and return values. Expanding on the example above, we can set our return value using the EventObject::setReturnVal() method. This will output "square".
Code Block |
---|
language | php |
---|
firstline | 1 |
---|
title | /app/controllers/my_controller.php | firstline | 1 |
---|
linenumbers | true |
---|
|
<?php
class MyController extends AppController {
public function index() {
$this->Events->register("EventName", array($this, "callbackMethod"));
$event = new EventObject("EventName", array("square", "pink"));
$event = $this->Events->trigger($event);
echo $event->getReturnVal();
return false; // don't render a view
}
public function callbackMethod(EventObject $event) {
$params = $event->getParams();
$event->setReturnVal($params[0]);
}
}
?> |
...