Afin de comprendre le rôle du « cache de vue » ou des « cache blocks » (détaillé dans les prochains chapitres), il est important au préalable de bien différencier deux concepts qui sont souvent confondus :
- La compilation des templates, qui est abordé dans ce chapitre
- Le cache de template, qui désigne en fait la mise en cache des contenus des cache-block. Le mécanisme de cache-block sera détaillé dans un prochaine chapitre
“
La confusion entre ces 2 systèmes de caches provient des différentes interfaces et documentation, qui exploite l'expression "cache de template", sans préciser s'il s'agit de la compilation ou des fichiers de cache de template-block liés au cache-block
”
A quoi sert la compilation des template ?
Lorsque la directive de compilation des templates est activée, tous vos fichiers de templates péniblement rédigés (*.tpl) sont transformés ou plutôt « compilés » (désolé pour les puristes) en PHP. Ainsi lorsqu'un internaute demande l'affichage d'une page, cette page nécessite forcement l'exécution d'un certain nombre de templates (quelques dizaine la plupart du temps)
- Situation 1 : Ces templates n'existent pas dans leur version « compilée » : eZ Publish va d'abord compiler les templates impliqués (transformer la syntaxe eZTemplate des fichiers .tpl en syntaxe PHP), puis rendre disponible la version compilée (donc en PHP) pour la future construction du cache de vue ou des « cache blocks ». On pourrait résumer cette séquence en « TPL > PHP > xHTML (ou autre) »
- Situation 2 : Ces templates existent dans leur version « compilés » : lors de la construction du cache de vue, eZ Publish exécute directement le code PHP sans interpréter à nouveau les fichiers de template en syntaxe eZTemplate des fichiers .tpl. On pourrait résumer cette séquence en « PHP > xHTML (ou autre) »
Cette « situation 1 » (templates compilés à la volée) peut s'avérer dramatique sur un site à fort trafic et ne devrait jamais se produire en production. En effet, la compilation des templates nécessite une énorme consommation de ressource (RAM/CPU seulement, pas SQL) susceptible de générer toute sorte d'erreurs si le trafic concurrent est important, et si le "stalecache" n'est pas activé (concept détaillé plus loin).
Dans tous les cas de figure il est impératif :
- D'activer la compilation des templates sur un site en production
- De ne jamais supprimer massivement le cache de template
- pas de « php bin/php/ezcache.php --clear-all –purge »
- pas de « php bin/php/ezcache.php –clear-id=template », qui ne supprime pas le cache de template block, mais l’ensemble des versions compilés des templates
- pas de « php bin/php/ezcache.php –clear-tag=template », qui supprime à la fois les caches compilés et les le cache de template block
- Lors d'une mise à jour, de forcer la recompilation ciblée des templates ayant été modifiés, et uniquement ceux ayant été modifié (voir plus loin comment procéder)
Note : La compilation est activée par défaut (site.ini), mais souvent désactivés lors des phases de développement, tests ou autre. Il est donc important de vérifier qu'ils sont bien activés avec une mise en production du site.
settings/override/site.ini.append.php / [templatesettings]
TemplateCompile=enabled # compile les templates dans /template/compiled/
NodeTreeCaching=enabled # pré compile les templates dans /template/tree/, par défaut si TemplateCompile est enabled
Il ne faut pas confondre ces 2 paramètres avec celui d'activation du cache de template :
TemplateCache=enabled # met en cache les contenus des cache-block /template-block/
Comment sont stockés les templates compilés ?
Pour les courageux qui sont encore attentifs et qui souhaitent en savoir plus, eZ Publish stocke les versions compilées des templates dans le répertoire :
{VarDir}/cache/template/compiled/
{VarDir} = valeur du paramètre VarDir dans le site.ini (ou votre surchage spécifique), généralement "var/monsite/"
Les noms des fichiers sont relativement explicites :
{nomdutemplate}-{hash}php
par exemple : pagelayout-49f4458d0b68aec3cf2de63a6918fd61.php
Le hash est calculé selon 2 méthodes différentes, en fonction du paramètreShareCompiledTemplates (section [TemplateSettings] du site.ini)
Extrait de lib/eztemplate/classes/eztemplatecompiler.php
if ( $shareTemplates )
$cacheFileKey = $key . '-' . $language;
else
$cacheFileKey = $key . '-' . $internalCharset . '-' . $language . '-' . $useFullUrlText . $accessText . "-" . $pageLayoutVariable . '-' . eZSys::indexFile();
$cacheFileName = $extraName . md5( $cacheFileKey ) . '.php';
return $cacheFileName;
Tableau des éléments de la clé de hash, en mode ShareCompiledTemplates=disabled
|
Elément de la clé de hash
|
Signification
|
Exemple de valeur
|
|
key
|
MD5 du chemin complet du template
|
md5(‘extension/ezwebin/design/ezwebin/templates/pagelayout.tpl’)
|
|
internalCharset
|
Le charset interne
|
utf-8
|
|
language
|
La langue définie pour le siteaccess utilisée lors de la compilation
|
fre-FR
|
|
useFullUrlText
|
En fonction de la directive UseFullUrl (layout.ini) si le template est compilé lors de l'appel d'un URL de type « layout/set/... » (module layout)
|
full | relative
|
|
accessText
|
Nom du site siteaccess utilisée lors de la compilation, avec un « - » devant
|
-site_admin
|
|
pageLayoutVariable
|
Nom du pagelayout personnalisé, si le template est compilé lors de l'appel d'un URL de type « layout/set/print » par exemple (module layout)
|
print_pagelayout.tpl
|
|
indexFile
|
La racine de l'index du site, qui peut varié selon divers paramètres, comme par exemple : le nom du siteaccess en mode « URI », ou encore la racine « layout/set/... »
|
site_admin | layout/set/print
|
|
extraName
|
Le nom du template, sans le « .tpl », avec un « - » à la fin
|
pagelayout-
|
La clé de hash est donc constituée de plusieurs paramètres combinables, qu’il faut impérativement connaitre afin de bien comprendre et maîtriser l'impact d'une suppression complète des templates compilés. En effet, un site multi-langues, avec de nombreux siteaccess, et une utilisation massive du module 'layout' (layout/set/... ce qui est tout à fait déconseillé par ailleurs, mais c'est un autre sujet) peut générer un grand nombre de combinaisons possibles de caches compilés, autant de cache à reconstruire lors d'une expiration massive.
Note : Les plus attentifs auront remarqués la présence du répertoire « {VarDir}/cache/template/tree/ ». Ce répertoire contient une sorte de pré-cache ou « arbre de compilation », qui n’est présent que lorsque le setting NodeTreeCaching est activé, et qui accélère la compilation des différentes variantes d'un même template (par exploitation de l'arbre PHP de compilation plutôt que le .tpl d'origine). Lors de suppression manuelles et ciblées des caches (rm), il peut être nécessaire de supprimer également le fichier correspondant dans le répertoire en question, sous le nom de [hash]-[nomdutemplate].php
Travailler en mode ShareCompiledTemplates
Lorsque l’on active le paramètre ShareCompiledTemplates=enabled (section [TemplateSettings] dusite.ini), la clé de hash du stockage des templates compilés est alors beaucoup plus triviale, à savoir le chemin du template et la langue du siteaccess courant :
Tableau des éléments de la clé de hash, en mode ShareCompiledTemplates=enabled
|
Elément de la clé de hash
|
Signification
|
Exemple de valeur
|
|
key
|
MD5 du chemin complet du template
|
md5(‘extension/ezwebin/design/ezwebin/templates/pagelayout.tpl’)
|
|
language
|
La langue définie pour le siteaccess utilisée lors de la compilation
|
fre-FR
|
Cette configuration est tout à fait adaptée à des instances eZ Publish propulsant de nombreux siteaccess, comme par exemple des usines à site, dont on ne maîtrise pas le nombre de siteaccess dans le temps
Cependant, il faut être attentif aux valeurs des settings (fichiers INI) spécifiques à chaque siteaccess, dont les valeurs sont par défaut compilés dans les templates. Il est donc nécessaire de charger dynamiquement ces valeurs de settings à chaque exécution des templates, en utilisant :
- Soit la directive globale DynamicTemplateMode=enabled (site.ini [eZINISettings])
- Soit au cas par cas dans l’utilisant de l’opérateur de template eZINI ( paramètre ‘dynamic’ )
Comment forcer la recompilation d'un lot de templates spécifiques ?
Pour forcer la recompilation d'un ou plusieurs templates en particulier (2 templates d'ezwebin dans cet exemple) :
php bin/php/eztc.php -s monsiteaccess --force extension/ezwebin/design/ezwebin/templates/pagelayout.tpl extension/ezwebin/design/ezwebin/templates/page_leftmenu.tpl
Résultat :
Compiled template file: extension/ezwebin/design/ezwebin/templates/pagelayout.tpl
Compiled template file: extension/ezwebin/design/ezwebin/templates/page_leftmenu.tpl
Lorsque la liste des templates est un peu longue, on peut se simplifier la tâche en utilisant une liste stockée dans un fichier TXT ou encore en résultat d’une commande ls / find ou autre...
Compile tous les templates d’ezwebin qui commencent par “page_header_” :
find extension/ezwebin/ -name "page_header_*.tpl"| xargs php bin/php/eztc.php --force
Compile tous les templates contenu dans le fichier template_list.txt :
cat template_list.txt | xargs php bin/php/eztc.php --force
Documentation officielle :
https://auth.ez.no/ezpublish/documentation/development/scripting/supplied_scripts/template_compiler
Attention : Le chapitre précédent nous apprend que la clé de hash d'un template compilé exploite le paramètre $pageLayoutVariable. eZ Publish ne déduit cette valeur que lorsqu'elle est appelé dans une URL de type « layout/set/... », à la volée dans le index.php. Le script eztc.php ne peut donc pas connaître et prévoir à l'avance les diverses combinaisons possible.
Pour le dire autrement, lorsqu'on utilise le module layout :
- eZ Publish compile autant de version des templates que de layout différents exploités, par exemple un template « page_head.tpl » existera en 4 versions si 3 layouts supplémentaire sont exploités (version par défaut, 3 version spécifiques)
- Le script eztc.php ne recompile que le layout par défaut, les 3 autres compilations seront effectuées par appel frontal des URL concernées. Pour mettre à jour ces templates spécifiques sans purger l'ensemble du cache, il faudra donc supprimer individuellement les versions compilés de ces templates dans le répertoire {VarDir}/cache/template/compiled/, puis attendre leur appels par des internautes (impact généralement négligeable en performance lorsque l'opération est ciblée sur un seul lot de templates)
Pour supprimer manuellement les différentes variantes d’un template compilé afin de forcer la recompilation à la volée (par exemple pour le page_head.tpl) :
find var/ezflow_site/cache/template -name "page_head-*"| xargs rm
Comment faire expirer le cache des overrides de templates ?
Lorsque vous ajoutez des templates dans votre extension spécifique, et que vous définissez de overrides sur ces templates, 2 caches sont impliqués dans cette opération :
- Le cache de la liste des répertoires de designs par site_access invoqués progressivement, stocké dans {VarDir}/cache/designbase_{hash}.php. Le {hash} est constitué d’un md5 du site_access invoqué
Il est possible de faire expirer ce cache par la commande :
php bin/php/ezcache.php -s monsiteaccess --clear-id=design_base
Le cache de la liste des overrides de templates par site_access invoqués progressivement, stocké dans {VarDir}/cache/override/override_{hash}.php. Le {hash} est constitué d’un md5 :
- du tableau des répertoires /design (design.ini [ExtensionSettings] DesignExtensions[])
- du SiteDesign “standard”
- du SiteDesign déclaré dans site.ini [DesignSettings] SiteDesign
Il est possible de faire expirer ce cache par la commande :
php bin/php/ezcache.php -s monsiteaccess --clear-id=template-override
