The template debugging tools

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;

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

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_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.

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=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).

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

var_mode=traduction

The var_mode=traduction parameter is used to parse the language strings used in a page. When used, the language strings present in the page are highlighted:

• the translated language strings are highlighted, an info bubble giving the source item and the translation language is displayed when you hover on the chain,
• nonexistent language strings flash red.

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 "N°" 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

Adding into config/mes_options.php:

- Deactivate SPIP cache

<?php
define('_NO_CACHE', -1);

or by clicking on the button natively present since SPIP 3: "Temporarily deactivate the cache"

- Deactivate CSS and Javascript caches (files located inlocal/cache-js/ and local/cache-css/

<?php
define('_INTERDIRE_COMPACTE_HEAD_ECRIRE', true);

-  Activate PHP error reporting

<?php
error_reporting(E_ALL^E_NOTICE);
ini_set ("display_errors", "On");

-  Display all errors in SPIP

<?php
define('SPIP_ERREUR_REPORT',E_ALL);

-  Increase log size to 500 KB

<?php
$GLOBALS['taille_des_logs'] = 500;

-  Limit size logs to 500000 lines

<?php
define('_MAX_LOG', 500000);

-  Add in the logs the file, the line and the name of the function from which the log is generated.

<?php
define('_LOG_FILELINE',true);

-  Obtain all logs (SPIP3)

<?php
define('_LOG_FILTRE_GRAVITE',8);

-  Add the logs on everything related to permissions (function autoriser_dist). This constant has been removed in SPIP 3.1

<?php
define('_DEBUG_AUTORISER', true);

-  Since Spip 2.1.22 and 3.0.9, this option makes it possible to indicate in the MySQL logs (log/mysql-slow.log) the URL corresponding to the "slow" requests:

<?php
define('_DEBUG_SLOW_QUERIES', true);

-  Since Spip 3.0.9 (and, in SPIP 2.1 with the plugin "iterateurs"), this option allows you to follow loops that require more than 5 seconds (5000 ms) to execute

<?php
define('_BOUCLE_PROFILER', 5000);

To summarize to use ONLY on a site in DEVELOPMENT, you can copy / paste all this into your config/mes_options.php :

<?php
define('_NO_CACHE', -1);
define('_INTERDIRE_COMPACTE_HEAD_ECRIRE', true);
error_reporting(E_ALL^E_NOTICE);
ini_set ("display_errors", "On");
define('SPIP_ERREUR_REPORT',E_ALL);
$GLOBALS['taille_des_logs'] = 500;
define('_MAX_LOG', 500000);
define('_LOG_FILELINE',true);
define('_LOG_FILTRE_GRAVITE',8);
define('_DEBUG_SLOW_QUERIES', true);
define('_BOUCLE_PROFILER', 5000);