There are lots of settings and helper functions which can really assist with debugging your eZ Publish site. Here are the key tips I use when I need to work through any issues. These involve making a number of changes to your ini settings to ensure debug/caching is set correctly when developing. One key thing though is to make sure any debug/cache settings you change must be reset when you move your site to production (if you need to check the logs on production, go into the var/logs directory in the root of eZ Publish).
There is an excellent three part tutorial that is worth reading by Łukasz Serwatka for which a link can be found under the further reading section.
Updating your Debug Settings
Here are the key settings for debugging, they are all in site.ini:
Ensuring debug is shown on the page:
site.ini [DebugSettings] DebugOutput=enabled
Limiting debug to your chosen IP addresses:
site.ini [DebugSettings] DebugByIP=enabled DebugIPList[] DebugIPList[]=91.192.53.264
Limiting Debug to your chosen users
site.ini [DebugSettings] DebugByUser=enabled DebugUserIDList[] DebugUserIDList[]=14 DebugUserIDList[]=21
Showing templates being used in the page source (show start/end points of each template) / Display a list of templates used at the bottom of Debug Please note that if ShowUsedXHTMLTemplates is also enabled, then the source code will not show the commented template names
site.ini [TemplateSettings] Debug=enabled ShowUsedTemplates=enabled
Display the debug as a popup or inline
Please note this also requires changes to your .htaccess file
site.ini [DebugSettings] Debug=popup
The .htaccess needs to have the following rewrite rules added (as found here):
RewriteRule ^ /var/cache/debug.html .* – [L]
RewriteRule ^/var/[^/]+/cache/debug.html.* – [L]
Showing all SQL queries in the debug/flagging queries which take longer than milliseconds
site.ini [DatabaseSettings] SQLOutput=enabled SlowQueriesOutput=300
Updating your Cache Settings
While developing, it is a great help to remove the caching system eZ Publish has in place. By removing it, it ensures all of your template updates are made immediately. Below are the key settings you need to update (again, these are in site.ini):
Ensuring templates are not compiled
site.ini [TemplateSettings] TemplateCompile=disabled
Ensuring view caching does not take place
site.ini [ContentSettings] ViewCaching=disabled
Ensuring templates are not cached
site.ini [OverrideSettings] Cache=disabled
Outputting notices and warnings to the debug
This can be done both in your custom php code or within the template language itself.
To add a notice or warning in php:
eZDebug::writeNotice( "Message", 'Title' ); eZDebug::writeWarning( "Message", 'Title' ); eZDebug::writeError( "Message", 'Title' );
To add a notice in a template
{debug-log msg= 'outputting node' var=$node}
Outputting Variable Information
One of the first template operator I picked up was the attribute() operator. This returns a list of all fields within an object to a depth of your choosing. There are three optional parameters. If the first parameter is set to ‘show’, the values for each field are also shown. The second is the depth of fields you go to. By default this is set to 1. This means if one of the fields is an array, the operator will not iterate down into that as well. If you increase this too much, the amount of information you pull out can cause issues with loading the page so the most you would tend to use would be a depth of 2 or 3. The last parameter tells eZ whether to display the results as a table or not. Since it’s only being used for debug, this usually isn’t too relevant.
The example below will show all fields within the object to a depth of 3:
{$my_var|attribute('show',3)}Timing your code
debug-timing-point can be used around your template code to time it. This example is used around in the Zone template file for eZ Flow so we can time each block used in the page. The timing points show up in the timing points area of the page debug.
{debug-timing-point id=$block.name} {block_view_gui block=$block} {/debug-timing-point}
To do the same in php, the following can be used:
eZDebug::addTimingPoint( "My timing point start" ); for ($i=0;$i<200000000;$i++) { eZDebug::writeNotice( "Your code to time here", "Notice $i" ); } eZDebug::addTimingPoint( "My timing point end" );
Debugging the Command Line
When you’re running command line scripts, debug can be displayed using the code below. For a more complete list of the other parameters you can use, click here
$script = eZScript::instance( array( 'description' => ( "My brilliant script.\n\n" . "My fantastic script which does everything", 'debug-output' => true, 'debug-message' =>true ) );
Shouldn’t ViewCaching=disabled?
Well spotted! ;o)