Documentation : Sessions

Le système de session permet de stocker temporairement des variables, qui sont liées à un visiteur. L'intérêt est de faire des traitements dans un contrôleur en fonction des traitements effectuée précédemment dans les contrôleurs exécutés préalablement.
Chaque session est liée à un navigateur par le biais d'un cookie déposé au premier accès. Cela est transparent car géré par le framework.

L'objet de gestion des sessions est créé automatiquement par Temma, si la configuration le prévoit. Il est alors disponible dans les contrôleurs en utilisant l'attibut privé $this->_session.
Cet objet ne propose que deux méthodes : get() et set().

get(string, [mixed])

Cette méthode sert à récupérer les données d'une variable placée préalablement en session, dont le nom est passé en paramètre.
Le second paramètre, optionnel, sert à définir la valeur qui sera retournée si la variable n'existe pas en session. Par défaut, la méthode retourne null si elle ne trouve pas la variable demandée.

Exemples d'utilisation :

// récupère les informations sur l'utilisateur courant
// (informations placées en session après l'identification de l'utilisateur)
$currentUser = $this->_session->get('user');

// récupération du panier de commande de l'utilisateur courant
// (s'il n'existe pas, on l'initilise avec un tableau vide)
$basket = $this->_session->get('basket', array()); 
						
set(string, [mixed])

Cette méthode sert à enregistrer une variable de session. Le nom de la variable est passé en premier paramètre, et sa valeur en second paramètre.
Si le second paramètre n'est pas défini (ou est passé à null), la variable est effacée de la session si elle existait.

Exemples d'utilisation :

// enregistrement des informations de l'utilisateur courant (après identification)
$this->_session->set('user', $user);

// effacement des informations de l'utilisateur courant (après déconnexion)
$this->_session->set('user', null);
// identique à la ligne précédente
$this->_session->set('user');
						

Documentation : Cache

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 précisément pour chaque variable.

Temma crée automatiquement l'objet de gestion du cache, si la configuration le prévoit. Cet objet est disponible dans les contrôleurs en passant par l'attribut privé $this->_cache, et offre sept méthodes : get(), set(), setExpiration(), disable(), enable(), setPrefix() et clear().

set(string, mixed, [int])

Cette méthode sert à ajouter une donnée en cache. Le premier paramètre est le nom de la variable de cache. Le second paramètre est la valeur à enregistrer. Le troisième paramètre est la durée (en secondes) avant expiration de la variable ; si la durée n'est pas fournie, la valeur par défaut sera utilisée (24 heures).

Exemple d'utilisation :

// la même chose, en utilisant la durée d'expiration par défaut
$this->_cache->set('nom de la variable', $data);

// écriture d'une variable pour une durée de 2 semaines
$this->_cache->set('nom de la variable', $data, 604800);
						
get(string, [function])

Cette méthode permet d'aller chercher les données liées à une variable de cache. Le premier paramètre est le nom de la variable de cache à récupérer. Si la variable de cache n'existe pas (elle n'a pas été créée ou a déjà expiré), la méthode retourne null.

Exemple d'utilisation :

// on cherche un article en cache
$cacheVarName = "article-$articleId";
$article = $this->_cache->get($cacheVarName);

if (!$article) {
    // l'article n'était pas présent en cache, on va le cherche en base
    $article = $this->_dao->get($articleId);
    $this->_cache->set($cacheVarName, $article);
}
						

Il est possible d'utiliser une fonction anonyme, passée en second paramètre, pour remplir automatiquement le cache si jamais la variable n'est pas déjà enregistrée (ou si elle a déjà expiré). La valeur retournée par cette fonction sera alors mise en cache, et retournée par la méthode get(). La donnée sera mise en cache avec une durée d'expiration correspondant à la durée par défaut.

Exemple d'utilisation :

$dao = $this->_dao;
$article = $this->_cache->get("article-$articleId", function () use ($dao, $articleId) {
    return ($dao->get($articleId));
});
						
setExpiration([int])

Cette méthode permet de modifier la valeur d'expiration par défaut. Après l'avoir modifiée, tous les appels à set() effectués sans spécifier la durée d'expiration utiliseront cette durée.
La durée d'expiration par défaut ne peut pas être supérieure à 2592000 secondes (soit 30 jours).
Si la méthode est appelée sans paramètre, la durée d'expiration par défaut est remise à sa valeur initiale de 86400 secondes (24 heures).

Activation et désctivation

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é.

enable() permet de réactiver l'utilisation du cache (après un appel à disable(), par exemple).

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é
$self = $this;
$article = $this->_cache->get("article-$articleId", function () use ($self) {
    // l'attribut "_someDao" doit avoir une visibilité publique
    return ($self->_someDao->get($articleId));
});

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

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.

setPrefix([string]) 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.

clear(string) sert à invalider toutes les variables de cache qui partagent le même préfixe.

Exemple d'utilisation :

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

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

// effacement de toutes les 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');