Présentation

Le cache sert habituellement à stocker des informations qui sont souvent accédées en lecture. Il est alors préférable de ne pas aller les lire en base de données à chaque accès, mais plutôt de les agréger et de les placer en cache ; les lectures suivantes seront plus rapides.

Il faut comprendre que, contrairement aux sessions, les variables de cache sont communes à l'ensemble de l'application. Il est donc important de réfléchir soigneusement au nommage des variables, pour pouvoir les retrouver facilement.
Autre différence, les variables de cache ont pour vocation de rester temporaires. Elles expirent au bout d'un certain temps, qui peut être défini de manière globale ou précisément pour chaque variable. Par défaut, la durée d'expiration est de 24 heures.

Si vous avez correctement configuré les paramètres de connexion au serveur Memcached, Temma crée automatiquement un objet de type \Temma\Base\Cache. Par convention, nous partirons du principe que vous avez nommé cette connexion cache dans le fichier temma.json (voir la documentation de la configuration).

Dans les contrôleurs, la connexion au cache est alors disponible en écrivant :

$this->cache

Dans les autres objets gérés par le le composant d'injection de dépendances, la connexion au cache est accessible en écrivant :

$this->_loader->dataSources['cache']

Écriture de données

Pour créer ou modifier une variable de cache, il suffit d'utiliser l'objet comme un tableau associatif :

$this->cache['myVariable'] = $value;

Si la valeur assignée à la variable vaut null, la variable est effacée de la session.

Il est possible d'écrire une variable de cache en lui donnant une durée de vie maximale, grâce à la méthode set(). Elle prend en paramètre le nom de la variable, sa valeur, et la durée de mise en cache en secondes.
Voici un exemple d'utilisation :

// la donnée restera en cache pendant 1 heure
$this->cache->set('myVariable', $value, 3600);

Cette méthode retourne l'ancienne valeur de la variable (si elle existait, sinon elle retoure null).

Effacement de données

Pour détruire une variable de cache :

unset($this->cache['myVariable']);

Lecture de données

Pour lire des données depuis le cache, il suffit d'utiliser l'objet comme un tableau associatif :

$user = $this->cache['user:12'];

Avec la méthode get(), il est aussi possible de lire une variable de cache et, si elle n'existe pas, exécuter une fonction anonyme, dont la valeur de retour sera stockée en cache (sous le nom demandé) et enfin retournée :

$userId = 12;
$user = $this->cache->get("user:$userId", function () use ($userId) {
    $sql = "SELECT * FROM Users WHERE id = '$userId'";
    $user = $this->db->queryOne($sql);
    return ($user);
});

Dans l'exemple ci-dessus, on essaye de récupérer les informations sur un utilisateur depuis le cache. Si le cache contient déjà la donnée, on les récupère directement. Si par contre la donnée n'est pas présente en cache, la fonction anonyme est exécutée. Celle-ci fait une requête sur la base de données afin de récupérer les informations sur l'utilisateur ; la fonction retourne ces informations, qui sont automatiquement mises en cache, et retournées par la méthode get().

Comme avec la méthode set(), il est possible de fournir une durée de vie maximale pour la mise en cache :

// la donnée sera stockée en cache pendant 5 minutes
$var = $this->cache->get('myVariable', function () {
    return ('some value');
}, 300);

Durée de mise en cache

La méthode setExpiration() sert à définir la durée de mise en cache par défaut. Cela permet d'éviter de le définir explicitement à chaque fois qu'une donnée est écrite en cache.
Elle prend un paramètre, qui est la durée de vie maximale des données en cache, exprimée en secondes. Par défaut, la durée est de 86400 secondes (soit 24 heures).
Cette méthode retourne l'instance de l'objet de cache.

// expiration par défaut d'une heure
$this->cache->setExpiration(3600);

// expiration de 5 minutes, suivi d'un ajout de donnée
$this->cache->setExpiration(300)->set('aa', 'bb');

Vous pouvez utiliser la méthode getExpiration() pour connaître la durée de mise en cache actuellement configurée.

// on veut s'assurer que l'expiration est d'au moins 1 heure
$exp = $this->cache->getExpiration();
if ($exp < 3600)
    $this->cache->setExpiration(3600);

Gestion de préfixe

Ce que nous nommons "préfixes" est un label qui est ajouté aux noms des variables de cache. Leur intérêt est de pouvoir gérer toutes les variables de cache possédant le même préfixe, pour les invalider en une seule opération.

La méthode setPrefix([string $prefix]) sert à définir le préfixe des variables qui vont être traitées lors des appels à get() et set() qui suivront. En l'appelant sans paramètre, on supprime l'utilisation des préfixes.
Elle retourne l'instance de l'objet de cache.

La méthode clear(string $prefix) sert à invalider toutes les variables de cache qui ont le préfixe passé en paramètre.
Elle retourne aussi l'instance de l'objet de cache.

Exemple d'utilisation :

// définition d'un préfixe
$this->cache->setPrefix('sites');
// ajout de variables de cache
$this->cache->set('A', $siteA);
$this->cache->set('B', $siteB);
$this->cache->set('C', $siteC);

// définition d'un second préfixe
$this->cache->setPrefix('articles');
// ajout de variables de cache
$this->cache->set('Y', $articleY);
$this->cache->set('Z', $articleZ);

// effacement des variables appartenant au premier préfixe
// ("A", "B" et "C")
$this->cache->clear('sites');

// arrêt de l'utilisation du préfixe "articles"
$this->cache->setPrefix();

// récupération d'une variable préfixée
$data = $this->cache->setPrefix('articles')->get('Z');

Il est possible de connaître le préfixe en cours grâce à la méthode getPrefix() :

$prefix = $this->cache->getPrefix();
if ($prefix != 'sites')
    $this->cache->setPrefix('sites');

Activation/désactivation du cache

La méthode disable() sert à désactiver temporairement l'utilisation du cache. Tous les appels subséquents ne retourneront pas d'erreur, mais aucun accès au cache ne sera effectué.
La méthode enable() permet de réactiver l'utilisation du cache (après un appel à disable(), par exemple).
Ces deux méthodes retournent l'instance de l'objet de cache.

Exemple d'utilisation :

// désactivation du cache
$this->cache->disable();

// la fonction anonyme sera systématiquement exécutée,
// car le cache est désactivé
$article = $this->cache->get(
    "article:$articleId",
    function () use ($articleId, $dao) {
        return ($dao->get($articleId));
    }
);

// réactivation du cache et enregistrement d'une variable
$this->_cache->enable()->set('name', $value);

La méthode enable() réactive le cache qui a été temporairement désactivé. Elle retourne aussi l'instance de l'objet de cache.

$this->cache->enable();

Pour savoir si le cache est activé ou désactivé, vous pouvez utiliser la méthode isEnabled(), qui retourne true si le cache est activé, et false sinon.

if (!$this->cache->isEnabled())
    print("Cache désactivé");