Skip to content
Mugo ESI is a framework to enable you to embed ESI widgets into your eZ Publish 4.x / legacy website.
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.

Mugo ESI

What is it?

Mugo ESI is a framework to enable you to embed ESI widgets into your eZ Publish 4.x / legacy website. These widgets will work behind Varnish or another reverse proxy that supports ESI. If you are accessing the site without Varnish for testing purposes, it will load the widget using Ajax in order to ensure that it is loaded dynamically. In the future, we might add support to make a direct module view call.

In short, Mugo ESI comes with a template operator that will detect, based on the presence of a Surrogate-Capability request header, whether to support ESI.

Your actual ESI widget is a module view following the pattern: /esiwidget/view/(widget)/widget_name

The TTL of your widget can be set in your custom PHP function or in an INI file.

How to use it?

There is an example ESI widget "timestamp_example" included in the extension.

Supposing that you want to create a new widget that just shows the current user's name, you would do the following:

Create mugo_esi.ini.append.php in your own extension and add:


Create extension/yourextension/classes/myesiwidgets.php:

 * A class containing functions for each dynamic widget
class MyESIWidgets
     * Return a single array containing all of the data you need as array elements
     * You can set the TTL with an element 'ttl' and a value in seconds
    public static function usernameAction()
        $user = eZUser::currentUser();
        $username = $user->attribute( 'contentobject' )->attribute( 'name' );
        return array( 'username' => $username );

Create extension/myextension/design/standard/templates/esiwidget/widgets/username.tpl ("username" coming from the name of your widget in the INI file) and output the username:


Use your new widget! In the relevant template, call the widget:

{mugo_esi_widget( 'username' )}

You can pass parameters to the esi widget and they should be passed as GET parameters since we support multiple, here is one example on how to pass the param 'tagID' to the widget:

{mugo_esi_widget( 'paramtest', hash( 'tagID', $tagID ) )}

And you can read the parameter using the eZHTTPTool class:

class MyESIWidgets
    public static function paramtestAction()
        $tagID = eZHTTPTool::hasGetVariable('tagID') ? eZHTTPTool::getVariable('tagID') : false;
        return array('tag_id' => $tagID);

You must include the following code in your pagelayout in order to support ESI widgets in full view templates. This is to ensure that eZ Publish will pass the HTTP header informing Varnish that there are ESI tags in the response.:

{if is_set( $module_result.content_info.persistent_variable.surrogate )} {set_header_variable( 'Surrogate-Control', 'abc=ESI/1.0' )} {/if}

You can’t perform that action at this time.