Carnet Wiki

30. API CacheLab 2. Actions globales par type d’invalidation

Version 6 — 5 months ago JLuc

Ce 2eme niveau d’intervention avec CacheLab est plus global puisque cette API permet d’intercepter les invalidations du cache quelque soit leur origine dans le code de SPIP ou d’un plugin, via la surcharge de la fonction suivre_invalideur . Cette surcharge permet d’interpréter le signal d’invalidation reçu et d’appliquer une stratégie d’invalidation ciblée spécifiquement pour ce signal.

Signaux d’invalidation

Il y a un petit nombre de types de signaux d’invalidation. À chaque forme de signal est associé un typesignal :

-  Pour chaque type d’objet d’un site, il y a un signal d’invalidation de la forme id=“objet/id_objet”, qui est activé lorsqu’un crée, modifie ou détruit un objet de ce type. Par exemple id=“article/1234”. Par simplification on dit parfois aussi que le signal est alors “article/1234”. Dans cet exemple, le typesignal est article

-  Certains autres signaux correspondent à des événements plus qu’à des objets : recalcul lors d’une demande via var_mode=recalcul. Là, le typesignal est recalcul.

-  Certaines modifications d’objets génèrent un signal exotique : le signal favori/article/1234 indique qu’une invalidation est demandée pour cause de changement d’un favori portant sur l’article 1234. Dans le cas des favoris, un autre signal est également généré à la suite : favori/auteur/98 qui indique qu’un favori concernant l’auteur 98 a été créé, modifié ou supprimé. Dans cet exemple, le typesignal est favori

Rq : Les signaux d’invalidations sont systématiquement lancés par le noyau de SPIP et en général par les plugins de la zone, mais ne sont pas utilisés dans le noyau de SPIP. Ils ne servent que pour d’éventuels plugins comme CacheLab. Il n’est donc pas exclu que certains plugins provoquant des invalidations ne renseignent pas du tout ou pas correctement ce signal : dans ce cas il faudra les corriger pour qu’ils fournissent un signal suffisamment descriptif du motif et du contexte d’invalidation.

Fonctions d’invalidations globales circonstancielles

Mise en oeuvre

Pour utiliser ce 2ème niveau d’API, le webmestre doit définir une stratégie d’invalidation pour chacun des types de signaux, au moyen d’une fonction dédiée dans laquelle il appellera les fonctions du 1er niveau : controler_invalideur et cachelab_cibler avec le paramètre $action='del' et avec les conditions et options permettant d’invalider précisément les caches qui deviennent périmés.

Pour traiter le signal "typesignal/...", il faut définir une fonction cachelab_suivre_invalideur_typesignal ($signal, $modif).
Les arguments sont :
-  $signal : le signal reçu.
-  $modif : a priori c’est true.
La fonction doit renvoyer renvoie true s’il faut ensuite poursuivre encore les traitements standards d’invalidation, ou false, si le signal a été entièrement traité et qu’il n’y a plus rien à faire.

Pour En général pour un signal “unobjet/id_unobjet”, cette fonction pourra par exemple appeller appellera cachelab_cibler('del', array('objet'=>$objet, 'id_objet'=>$id_objet)); pour invalider tous les caches des squelettes ayant cet objet précis dans leur environnement. Il se peut, toutefois, que cela ne suffise pas, notamment lorsque cet objet peut figurer dans des listes : ces listes ne reçoivent pas les id des objets contenus mais des indications génériques (par exemple : “afficher 5 objets à partir du 10ème”).

On aura intérêt à Si les squelettes sont bien ranger à part rangés , il se peut que les squelettes des noisettes de listes, d’objet soient rangées dans un dossier “liste par exemple , ", et alors il sera possible d’appelerégalement :
cachelab_cibler('del', array('chemin'=>'liste'));.Et sinon, il faudra changer le rangement de vos squelettes pour pouvoir les facilement avec cachelab... par exemple en mettant vos listes dans un dossier “liste”.

Exemples :

// gérer une demande d'invalidation concernant un point GIS
function cachelab_suivre_invalideur_gis($cond, $modif) {
	include_spip ('inc/cachelab');
	cachelab_cibler('del', array ('chemin'=>'gis chemin'=>'json _')); // cibler gis_json, gis_article, etc
}@@@SPIP_DIFF8@@@
//   gérer  une  demande  d'invalidation  concernant  un  document
@@@SPIP_DIFF1@@@ @@@SPIP_DIFF8@@@function @@@SPIP_DIFF1@@@ @@@SPIP_DIFF8@@@cachelab_suivre_invalideur_document($cond@@@SPIP_DIFF1@@@ @@@SPIP_DIFF8@@@, @@@SPIP_DIFF1@@@ @@@SPIP_DIFF8@@@$modif@@@SPIP_DIFF1@@@ @@@SPIP_DIFF8@@@) @@@SPIP_DIFF1@@@ @@@SPIP_DIFF8@@@{
	@@@SPIP_DIFF1@@@ @@@SPIP_DIFF8@@@include_spip@@@SPIP_DIFF1@@@ @@@SPIP_DIFF8@@@ (' inc/cachelab ');
	@@@SPIP_DIFF1@@@ @@@SPIP_DIFF8@@@cachelab_cibler('del ', @@@SPIP_DIFF1@@@ @@@SPIP_DIFF8@@@array@@@SPIP_DIFF1@@@ @@@SPIP_DIFF8@@@ (' chemin'=>'documents '));
@@@SPIP_DIFF1@@@ @@@SPIP_DIFF8@@@}@@@SPIP_DIFF1@@@ @@@SPIP_DIFF8@@@
</@@@SPIP_DIFF1@@@ @@@SPIP_DIFF8@@@code@@@SPIP_DIFF1@@@ @@@SPIP_DIFF8@@@>@@@SPIP_DIFF1@@@ 
 
 
@@@SPIP_DIFF170@@@// gérer une demande d'invalidation concernant un document
function cachelab_suivre_invalideur_document($cond, $modif) {
	include_spip ('inc/cachelab');
	cachelab_cibler('del', array ('chemin'=>'documents'));
}

Ce 2eme niveau d’API permet donc de mettre en place une stratégie d’invalidation circonstanciée mais plus globale : chaque fonction répond à un signal d’invalidation spécifique, mais pour tout le site et quelque soit l’origine de l’invalidation de cet objet, et un traitement différent pour chaque non formulaire par formulaire ou autre bout de code invalidant .

Fonction decode_invalideur

La fonction decode_invalideur facilite la mise en place de fonctions globales contextuelles d’invalidation ciblée en décodant pour vous le signal d’invalidation. Cette fonction renvoie la valeur de l’identifiant de l’objet ayant généré le signal.
Elle reçoit 3 arguments
-  le signal
-  (optionnel) le type d’objet attendu (document, article, ...) s’il y en a un (ou vide sinon)
-  (optionnel) une variable passée en référence qui renverra le type d’objet réellement rencontré

Cette fonction sera utile pour cibler des caches précis lorsque ce sera nécessaire.
Exemple :

// gérer une demande d'invalidation issu d'un article
function cachelab_suivre_invalideur_article($signal, $modif) {
    include_spip ('inc/cachelab');
    $id_article = decode_invalideur($signal, 'article');
    cachelab_cibler('del', array ('chemin'=>'documents', 'objet'=>'article', 'id_article'=>$id_article));
}