SPIP

[ar] [ast] [bg] [br] [ca] [co] [cpf] [cs] [da] [de] [en] [eo] [es] [eu] [fa] [fon] [fr] [gl] [id] [it] [ja] [lb] [nl] [oc] [pl] [pt] [ro] [ru] [sk] [sv] [tr] [uk] [vi] [zh] Espace de traduction

Download

The template debugging tools

November 2010 — updated on : January 2014

All the versions of this article:

SPIP offers several native features made available to help webmasters when they need more information to debug a particular template.
These information functions are accessed by passing special variables in the URL of the page being called.


The "var_mode" and "var_profile" are applied by adding either ?var_mode=... (e.g. -titre-de-rubrique-?var_mode=...), or &var_mode=... (e.g. spip.php?article3&var_mode=...) to the end of the URL for the called page.
Their application will only work if you are logged in to the site as one of the administrators.

var_mode=calcul   and   var_mode=recalcul

Calling a page with "var_mode=calcul" regenerates the HTML code (calls the already compiled code) and refreshes the cache (creates the HTML files which will simply need to be read when the next call to that page is requested).

Calling a page with "var_mode=recalcul" regenerates the PHP code (performs a new compilation of the template), then also regenerates the HTML code (run an execution of the code which has just been compiled) and then again finally refreshes the cache (creates the HTML files which will be read the next time that page is called).
the recalculation of the page also regenerates the compressed CSS and JavaScript scripts.
the recalculation does not apply to the images (vignettes/thumbnails, images-typo/textual images, ...)

Either of these two calls can be executed by clicking on one of the administration buttons visible on the public page whenever you are logged in as an administrator;

var_mode=calcul

the first click calling "var_mode=calcul" (when the button’s title is accompanied with an asterisk, it is because the displayed page has been read from the cache);

var_mode=recalcul

a second click calls for a recalculation with "var_mode=recalcul".

Warning: You might be tempted to use &var_mode=recalcul for links inside your templates (to force an update to CSS or JavaScript content for example). This is a very bad practice that you should avoid since it consumes considerable server resources (causes constant re-compilation of the template).

var_mode=inclure

Calling a page with "var_mode=inclure" displays the name and path of each sub-component (inclure/include code or SPIP model) which is included within the page.

This makes it possible to check that the includes actually called by the page template are indeed those that have been specified, particularly important if you have overloaded any standard or plugin models by showing the full pathname to each included file.

var_mode=inclure

var_profile=1

Calling a page with "var_profile=1" displays the details of the SQL queries and the calculation times involved with each of them. The queries are sorted from the most time consuming to the least.

This function is particularly useful to find out what could be making a particular page display excessively slowly.
It allows you to view the SQL queries generated by each loop in the template (including those of any included templates or models) as well as any out of loop queries (noted as "Uncompiled") when generated by SPIP.

var_profile

This will display:

  • for each loop
    • the number of times that the loop (and therefore the SQL query) has been executed,
    • the time (in seconds) used by the loop (i.e. the time for the corresponding query multiplied by the number of executions of the loop),
    • the list (sorted in chronological order of all the queries generated by the page) of each execution of the query (which provides a link to the details of each query).
  • the uncompiled queries
  • the total time taken by all of the queries for the page
  • the details of each query run with
    • a statistical table showing the execution plan of the query,
    • the title of the query.
Warning: Remember to calculate the page with (&var_profile=1&var_mode=calcul) in order to avoid the cache being read, which would thereby cause false results to be displayed.

var_mode=preview

Calling a page with "var_mode=preview" from the private space is used to view an article which has been "proposed for publication" without actually needing to publish it on the public site.

var_mode=preview

var_mode=urls

Calling a page with "var_mode=urls" forces an update of all of the URLs included within that page.

var_mode=debug

Calling a page with "var_mode=debug" details the generation of a page (the SPIP loops - SQL queries - PHP code - SQL query statistics).

JPEG - 155.9 kb
var_mode=debug

This page displays info for the main template file as well as for any included template files:

  • the list of values of the environment context variables (#ENV) passed by the calling template,
  • the list of loops.

The various links can be used to access:

  • Template
    the textual code of the template (thereby avoids needing to have direct access to the .html file in order to read its contents),
    • results
      the code specifically generated by the template (any possible includes) which, once evaluated, will return the HTML to the browser,
    • code
      the PHP code generated by the compiler (an analysis moreover intended for core code developers) which, once executed, will generate the results (see above),
    • calcul
      the detail of the SQL queries and, for each of them, their execution times (see above for var_profile).
  • boucle
    the textual code of the complete loop (from <B_abc> through to <//B_abc>),
    • results
      the SQL query generated by the loop in question,
      a list of the first results returned by that query [1],
    • code
      the PHP code (generated by the compiler) for the specific function associated with that loop (an analysis mostly reserved for expert core code developers),
    • calcul
      the details and calculation time for the SQL query associated with that loop (see above for var_profile).

Display the contents of a table

Calling a page with the URL modifier ?page=table:name_of_the_table from the public space will display the contents of the named table as an array.
for example: ?page=table:articles for the spip_articles table.

The first line of this array lists the fields of the table in alphabetical order (warning: do not confuse the database record "" with the "id_..."); clicking on one of these fields will sort the results accordingly (ascending/descending order).

The second line is used to run a search for a specific field value.

All of the data are displayed in paginated mode in groups of 10 results per page.

Note: This function makes it possible to display ALL of the data for ANY table in the database, but can only be used by a logged in site administrator.

Obtaining even more information for debugging

-  Deactivate the SPIP cache by adding a line into config/mes_options.php:

define('_NO_CACHE', -1);

-  Activate PHP error reporting by adding this code into config/mes_options.php:

error_reporting(E_ALL^E_NOTICE);
ini_set ("display_errors", "On");
define('SPIP_ERREUR_REPORT', E_ALL^E_NOTICE);
define('SPIP_ERREUR_REPORT_INCLUDE_PLUGINS', E_ALL^E_NOTICE);

P.S.

Also refer to the workshop videos especially dedicated to this subject that were created during the 2009 SPIP days in Avignon: Bug and debug : level 1 and Bugs and PHP debug : level 2 (available in French only).

Footnotes

[1it is possible to modify the number of results displayed here by inserting a line to change the default parameter into the mes_options.php file in the config/ directory: define('_MAX_DEBUG_AFF', 'n');
(by default, in order to avoid displaying hundreds of results from loops that might be overly generic, the value of "n" for this global constant is set at 50).


Show the template of this page Site powered by SPIP | Translation area | Private area