L'exécution d'un bloc a pour résultat une portion de page (HTML) et certaines actions sur la page (ajouter une métadonnée pour la page, un script, un style, …). Ce résultat peut être caché, pour une durée déterminée. Par défaut, le cache est stocké sur disque. Il peut être stocké dans d'autres systèmes : memcached, redis, …

Depuis la version 3.5.0

L'attribut cache de blocks.xml gère l'activation du cache pour un bloc. La valeur est soit un nombre de secondes, soit un booléen :

• “true” est équivalent à CHANGE_CACHE_MAX_TIME secondes. CHANGE_CACHE_MAX_TIME étant une constante de projet valant 3600 par défaut
• “false” permet de désactiver par surcharge un cache activé sur un bloc standard

Exemple : par défaut, le bloc “modules_website_sitemap” (plan du site) est caché pendant 3600 secondes :

<blocks>
  <block type="module_website_sitemap" cache="true" />
</blocks>

Version antérieure à 3.5.0

Le cache était activé si getCacheDependencies() retournait un tableau non vide.

Si un cache doit être invalidé avant que le temps déclaré ne soit passé, on peut déclarer une “dépendance”. Les dépendances peuvent être :

• Un modèle de document : invalide le cache lorsque qu'un document de ce modèle est créé, modifié ou détruit
• Un tag : invalide le cache lorsque le tag est attribué ou ré-attribué
• Un identifiant d'un document : invalide le cache lorsque ce document est modifié

Note de version : l'attribut cache-deps utilisé plus loin dans cette section n'est supporté qu'à partir de la version 3.5.0 de RBS Change. Pour les version antérieures, seule la méthode getCacheDependencies() permettait d'informer des dépendances du bloc. L'invalidation sur le temps se faisait avec une dépendance “temps”, de syntaxe time:<nombre de secondes>.

Depuis la version 3.5.0

Pour déclarer une dépendance à un modèle de document, on renseigne l'attribut cache-deps avec la liste des modèles, séparés par des virgules. Entourer le modèle de crochets permet de cibler le modèle et l'ensemble de ses descendants.

Exemple : les dépendances du bloc “modules_website_sitemap” : le cache du plan du site est ainsi invalidé dès qu'un site, une page ou une rubrique est modifié.

<blocks>
  <block type="module_website_sitemap" cache="true"
   cache-deps="modules_website/website,[modules_website/page],modules_website/pageexternal,[modules_website/topic]" />
</blocks>

Depuis la version 3.5.0

Pour déclarer une dépendance à un tag, on renseigne cache-deps avec tags/<nom_complet_du_tag>. Le caractère “*” peut-être utilisé pour les tags “commençant par”.

Exemple : “modules_website_ConfigurableMenu” est invalidé dès qu'un tag commençant par “contextual_website_website_” est manipulé :

<blocks>
  <block type="modules_website_ConfigurableMenu" cache="true"
   cache-deps="tags/contextual_website_website_*,..." />
</blocks>

Pour déclarer une dépendance à un document précis, il faut implémenter getCacheDependencies() sur le bloc. Cette méthode retourne les dépendances du bloc à ajouter aux dépendances déclarées par cache-deps, sous la forme d'un tableau ; getCacheDependencies() complète l'attribut cache-deps.

Exemple : invalidation du cache sur modification du document principal

class mymodule_BlockMyblockAction
{
  /**
   * @return Array
   */	
  public function getCacheDependencies()
  {
    return array($this->getDocumentIdParameter());
  }
}

Avertissement : l'enregistrement des dépendances “statiques” (modèle, tag) n'est fait qu'une fois pour un bloc donné, alors que l'enregistrement des dépendances aux instances de documents est fait à chaque nouvelle mise en cache. Veillez donc à ne pas sur-utiliser cet type de dépendance.

Depuis la version 3.5.0

Chaque entrée de cache est associée à une clef, signature du contenu que le bloc génère.

Par défaut la clef est constituée de

• La langue courante
• Le site courant
• Le thème utilisé
• Le protocole utilisé (HTTP ou HTTPS)
• Les paramètres de configuration du bloc

Si le contenu du bloc varie en fonction d'autres paramètres, il faut les ajouter à la clef.

Exemple : le bloc “menu” met en exergue l'élément de menu “actif”, dépendant de la page courante. Le contenu varie donc en fonction de la page courante. Pour ajouter la page courante à la clef, le bloc renseigne l'attribut cache-key avec la valeur “page” :

<block type="modules_website_menu"
  cache="true" cache-key="page" />

Le tableau suivant liste les valeurs supportées par l'attribut cache-key. Les différentes valeurs peuvent être cumulées en les séparant par des virgules.

Exemple : bloc dont le contenu varie en fonction de la page courante, du document courant et du navigateur :

<block type="modules_mymodule_myblock" cache="true" cache-key="page,cmpref,nav" />

Si le contenu du bloc est fonction d'autres paramètres, il faut implémenter getCacheKeyParameters(), qui retourne un tableau associatif des valeurs déterminant le contenu généré ; le retour de getCacheKeyParameters() complète l'attribut cache-key.

Exemple : implémentation de getCacheKeyParameters() d'un bloc utilisant le paramètre “myParam” pour générer le contenu :

class mymodule_BlockMyblocAction extends website_BlockAction
{
  public function getCacheKeyParameters($request)
  {
    return array("myParam" => $request->getParameter("myParam"));
  }
}

Attention, seul la méthode “primaire” execute() est cachable de cette manière. Pour cacher une autre partie du code, vous pouvez utiliser directement la classe f_DataCacheService.

L'extension PHPTal change:cache permet de cacher des portions de gabarit. Ceci sera notamment utilisé lorsque les méthodes utilisées dans le gabarit sont lourdes et nombreuses.

L'attribut deps permet de déclarer les dépendances du cache (au même sens que défini plus haut).

La clef de cache est quant à elle générée à partir de la langue, du user agent courant et des autres paramètres placés sur la balise.