API day: le système de registre de TYPO3

L’API TYPO3 regroupe un nombre impressionnant de fonctionnalités dont certaines ne sont pas très connues.
Voici, par exemple, la gestion du système de registre dans TYPO3.

Cette fonctionnalité permet de regrouper des données de manière unique sur tout le site, sans devoir créer une table spécifique pour ces données.

A) Présentation

Il existe des cas de figures pour lesquels une seule variable est nécessaire pour l’ensemble d’un site.
On peut avoir par exemple l’activation d’un mode spécial pour le site comme un mode spécial « noël » ou un  mode « maintenance ».
On peut aussi imaginer des variables de configuration qui doivent pouvoir être mises à jour par les plugins eux même (contrairement au typoscript), comme la mise en place d’un affichage limité aux X premiers visiteurs.

L’extension « SOLR pour TYPO3 » utilise cette fonctionnalité pour regrouper les informations de connexion au serveur SOLR.

En temps normal, il serait nécessaire de créer une table dans la base de données. Cette table ne contiendrait qu’une seule variable.
Avec le système de registre, cela n’est plus nécessaire. Le registre permet justement de conserver des variables « unique » pour tout le site.

Via l’API de TYPO3, il est possible d’affecter et de consulter des données.
Il est aussi possible de nettoyer une variable unique ou tout un groupe de variables.
La valeur est automatiquement « sérialisée » lors de l’enregistrement dans la base, et « désérialisée » lors de sa récupération.

WordPress possède un système équivalent, appelé WordPress Setting API.

B) affectation d’une variable dans le registre

Pour déclarer une variable dans le registre de TYPO3, il faut faire appelle à la classe « t3lib_Registry ».
Pour l’appel, il est nécessaire de spécifier 3 paramètres :
– un « namespace » (en gros un identifiant permettant d’assurer l’unicité des variables)
– le nom de la variable
– la valeur à enregistrer

Pour le namespace, il faut utiliser un code qui commence par « tx_ » pour être compatible avec toutes les versions de TYPO3.
On peut par exemple utiliser la clé de l’extension qui utilisera le plus la variable.

<?php
   //on declare le registre
 $registre = t3lib_div::makeInstance('t3lib_Registry');
   //on declare les donnees a enregistrer
 $donnees = array(
   'donnee1' => $GLOBALS['EXEC_TIME'],
   'donnee2' => time(),
   'donnee3' => 'maintenance'
 );
   //on enregistre les donnees dans le registre
 $registre->set('tx_monnamespace', 'donneesGlobales', $donnees );
?>

C) Lecture d’une variable dans le registre

Pour récupérer une variable depuis le registre de TYPO3, il faut faire aussi appelle à la classe « t3lib_Registry » (comme de par hasard)
Cette fois ci, seulement 2 paramètres sont requis :
– le namespace
– le nom de la variable à récupérer

Cela sont les valeurs qui ont été utilisées lors de l’enregistrement dans le registre.

Une 3eme variable peut être fournie :
– une valeur par défaut en cas d’absence de données dans le registre

<?php
   //on declare le registre
$registre = t3lib_div::makeInstance('t3lib_Registry');
   //on declare les donnees par defaut
 $donneesParDefaut= array(
   'vide' => TRUE
 );
   //on recupere les donnees depuis le registre,
   //avec une valeur par defaut en cas d'absence de donnees (tableau : vide=>TRUE)
 $donnees = $registre->get('tx_monnamespace', 'donneesGlobales', $donneesParDefaut);
?>

D) nettoyage des données

Pour nettoyer les données présentes dans le registre il existe 2 fonctions :
– remove :  pour nettoyer une donnée précise
– removeAllByNamespace : pour nettoyer toutes les données ayant le même « namespace » (code d’unicité)

<?php
   //on declare le registre
 $registre = t3lib_div::makeInstance('t3lib_Registry');
   //on supprime une donnee precises
 $registre->remove('tx_monnamespace', 'donneesGlobales');
   //on supprime toutes les donnees du namespace
 $registre->removeAllByNamespace('tx_monnamespace');
?>

Il est important de noter que les données du registre ne sont pas vidées lorsque l’on vide les caches de TYPO3.

Il n’y a aucune instruction dans l’api de TYPO3 qui permet de vider intégralement la table de registre (seulement un nettoyage par namespace ou par namespace+nom d’une donnée).

E) Informations:

Testé sur TYPO3 v4.3 et toujours valide en v6.0.

ATTENTION :  à partir de la version 6.0, la déclaration change :

<?php
   //version 4.X
 $registre = t3lib_div::makeInstance('t3lib_Registry');
   //version 6.X
 $registre = \TYPO3\CMS\Core\Utility\GeneralUtility::makeInstance('TYPO3\\CMS\\Core\\Registry');
?>

La classe « t3lib_Registry » (ancienne classe) devrait être retirée du CMS à partir de la version 6.2

Sources :
– Buzz.typo3.org : 4.3 Treasure Trove: the system registry
– Using the system registry