Mugo Web main content.

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:

#Modify the final HTML to inject CDN domain

Then, implement your function CDNFunctions::outputFilter:

 * CDN functions
class CDNFunctions
     * Inject CDN domain before HTML output for design and content assets
     * This is run on the response/preoutput ezpEvent
    public static function outputFilter( $templateResult )
        $CDNDomain = '';
        $patterns = array();
        $patterns[0] = '@(["\'])(/extension/(?:.*?)/design/(?:.*?)/(?:stylesheets|flash|images|lib|javascripts?)/(?:.*?))\1@is';
        $patterns[1] = '@(["\'])(/var/(?:.*?)/storage/images(?:-versioned)?/(?:.*?))\1@is';
        $replacements = array();
        $replacements[0] = '\1' . $CDNDomain . '\2\1';
        $replacements[1] = '\1' . $CDNDomain . '\2\1';
        $templateResult = preg_replace( $patterns, $replacements, $templateResult );
        return $templateResult;

The example inserts the CDN domain name into your design file paths so that images, stylesheets, JavaScript, and so on are served through the CDN.

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()