eZ Publish code-level events, aka ezpEvent
By: Peter Keung | August 29, 2013 | eZ Publish development tips
The eZ Publish events system, known otherwise as "ezpEvent" (the name of the PHP class), supports multiple extension points into the content management system and also enables you to define your own extension points. It was quietly introduced in eZ Publish 4.5.
eZ Publish events consist of generic code-level "notifications" (to simply trigger other events) and "filters" (to modify some data), similar to WordPress's add_action and add_filter functions. The notifications and filters trigger your custom code in "listener" functions. Some of the events that you can hook into involve the caching, template results, content downloads, and session management systems.
Example: Injecting a CDN domain
Here is an example of how to filter / modify the final template result HTML to inject a CDN (content delivery network) domain to media file paths. This is very useful in order to speed up the delivery of your site.
This particular feature was introduced in eZ Publish 4.1 via the output filter, but replaced with an eZ Publish event in eZ Publish 4.5. Arguably, the events system is more general and flexible compared to having separate settings blocks for different features. "response/preoutput" is a filter that is passed the final HTML result; you can hook into this in order to modify the HTML result. To do so, there are only 2 steps.
First, register your listener function in an override of site.ini:
[Event] #Modify the final HTML to inject CDN domain Listeners=response/preoutput@CDNFunctions::outputFilter
Then, implement your function CDNFunctions::outputFilter:
Other examples and documentation
Another example of an event is the "content/cache" filter, which passes an array of node IDs whose view caches are about to be cleared. You could hook into this to, for example, trigger a cache clear at the CDN or reverse proxy level.
To trigger a custom event in your own code, use something like this for a filter:
$data = ezpEvent::getInstance()->filter( 'mugoobjectrelations/someevent', $data );
... and something like this for a notification:
ezpEvent::getInstance()->notify( 'mugoobjectrelations/someevent', $data );
For further documentation, consult the following:
- the doc/features/[4.5|4.7|5.0|5.1|5.2]/event.txt files in your eZ Publish directory
- the "ezpEvent" class in kernel/private/classes/ezpevent.php
- search the eZ Publish kernel files for ezpEvent->instance()