Rev 248 | Rev 291 | Go to most recent revision | Blame | Compare with Previous | Last modification | View Log | RSS feed
<?php// declare(encoding='UTF-8');/*** Classe Cache permettant de mettre en cache des données.* Basée sur les principes de Zend_Cache (Copyright (c) 2005-2010, Zend Technologies USA, Inc. All rights reserved.)** @category php 5.2* @package Framework* @author Jean-Pascal MILCENT <jpm@tela-botanica.org>* @copyright Copyright (c) 2010, Tela Botanica (accueil@tela-botanica.org)* @license http://framework.zend.com/license/new-bsd Licence New BSD* @license http://www.cecill.info/licences/Licence_CeCILL_V2-fr.txt Licence CECILL* @license http://www.gnu.org/licenses/gpl.html Licence GNU-GPL* @version $Id$* @link /doc/framework/*/class Cache {/** Socke les enregistrements du cache dans des fichiers textes. */const STOCKAGE_MODE_FICHIER = "Fichier";/** Socke les enregistrements du cache dans une base de données SQLite. */const STOCKAGE_MODE_SQLITE = "Sqlite";/** 'tous' (par défaut) : supprime tous les enregistrements. */const NETTOYAGE_MODE_TOUS = "tous";/** 'expiration' : supprime tous les enregistrements dont la date d'expériration est dépassée. */const NETTOYAGE_MODE_EXPIRATION = "expiration";/** 'avecLesTags' : supprime tous les enregistrements contenant tous les tags indiqués. */const NETTOYAGE_MODE_AVEC_LES_TAGS = "avecLesTags";/** 'sansLesTags' : supprime tous les enregistrements contenant aucun des tags indiqués. */const NETTOYAGE_MODE_SANS_LES_TAGS = "sansLesTags";/** 'avecUnTag' : supprime tous les enregistrements contenant au moins un des tags indiqués. */const NETTOYAGE_MODE_AVEC_UN_TAG = "avecUnTag";/*** Dernier identifiant de cache utilisé.** @var string $dernier_id*/private $dernier_id = null;/*** Les options disponibles pour le cache :** ====> (boolean) controle_ecriture : [write_control]* - Enable / disable write control (the cache is read just after writing to detect corrupt entries)* - Enable write control will lightly slow the cache writing but not the cache reading* Write control can detect some corrupt cache files but maybe it's not a perfect control** ====> (boolean) mise_en_cache : [caching]* - Enable / disable caching* (can be very useful for the debug of cached scripts)** =====> (string) cache_id_prefixe : [cache_id_prefix]* - prefix for cache ids (namespace)** ====> (boolean) serialisation_auto : [automatic_serialization]* - Enable / disable automatic serialization* - It can be used to save directly datas which aren't strings (but it's slower)** ====> (int) nettoyage_auto : [automatic_cleaning_factor]* - Disable / Tune the automatic cleaning process* - The automatic cleaning process destroy too old (for the given life time)* cache files when a new cache file is written :* 0 => no automatic cache cleaning* 1 => systematic cache cleaning* x (integer) > 1 => automatic cleaning randomly 1 times on x cache write** ====> (int) duree_de_vie : [lifetime]* - Cache lifetime (in seconds)* - If null, the cache is valid forever.** @var array $options les options disponibles pour le cache .*/protected $options = array('stockage_mode' => self::STOCKAGE_MODE_FICHIER,'stockage_chemin' => null,'controle_ecriture' => true,'mise_en_cache' => true,'cache_id_prefixe' => null,'serialisation_auto' => false,'nettoyage_auto' => 10,'duree_de_vie' => 3600,);protected $stockage = null;public function __construct($options, $options_stockage = array()) {$this->setOptions($options);if ($this->options['stockage_mode'] == self::STOCKAGE_MODE_FICHIER) {$this->stockage = new CacheFichier($options_stockage, $this);} else if ($this->options['stockage_mode'] == self::STOCKAGE_MODE_SQLITE) {$this->stockage = new CacheSqlite($options_stockage, $this);}$this->stockage->setEmplacement($this->options['stockage_chemin']);}private function setOptions($options) {while (list($nom, $valeur) = each($options)) {if (!is_string($nom)) {trigger_error("Nom d'option incorecte : $nom", E_USER_WARNING);}$nom = strtolower($nom);if (array_key_exists($nom, $this->options)) {$this->options[$nom] = $valeur;}}}/*** Permet de (re-)définir l'emplacement pour le stockage du cache.* En fonction du mode de stockage utilisé , l'emplacement indiqué correspondra au chemin du :* - dossier où stocker les fichiers pour le mode "fichier".* - fichier de la base de données pour le mode "sqlite".* @param string $emplacement chemin vers dossier (Cache::STOCKAGE_MODE_FICHIER) ou fichier base Sqlite (Cache::STOCKAGE_MODE_SQLITE)* @return void*/public function setEmplacement($emplacement) {if ($emplacement != null) {$this->executerMethodeStockage('setEmplacement', array($emplacement));} else {trigger_error("L'emplacement ne peut pas être null.", E_USER_WARNING);}}/*** Teste si un cache est disponible pour l'identifiant donné et (si oui) le retourne (false dans le cas contraire)** @param string $id Identifiant de cache.* @param boolean $ne_pas_tester_validiter_du_cache Si mis à true, la validité du cache n'est pas testée* @return mixed|false Cached datas*/public function charger($id, $ne_pas_tester_validiter_du_cache = false) {$donnees = false;if ($this->options['mise_en_cache'] === true) {$id = $this->prefixerId($id);$this->dernier_id = $id;self::validerIdOuTag($id);$donnees = $this->executerMethodeStockage('charger', array($id, $ne_pas_tester_validiter_du_cache));$donnees = $this->deserialiserAutomatiquement($donnees);}return $donnees;}/*** Test if a cache is available for the given id** @param string $id Cache id* @return int|false Last modified time of cache entry if it is available, false otherwise*/public function tester($id) {$resultat = false;if ($this->options['mise_en_cache'] === true) {$id = $this->prefixerId($id);self::validerIdOuTag($id);$this->dernier_id = $id;$resultat = $this->executerMethodeStockage('tester', array($id));}return $resultat;}/*** Sauvegarde en cache les données passées en paramètre.** @param mixed $donnees Données à mettre en cache (peut être différent d'une chaine si serialisation_auto vaut true).* @param string $id Identifiant du cache (s'il n'est pas définit, le dernier identifiant sera utilisé).* @param array $tags Mots-clés du cache.* @param int $duree_de_vie_specifique Si != false, indique une durée de vie spécifique pour cet enregistrement en cache (null => durée de vie infinie)* @return boolean True si aucun problème n'est survenu.*/public function sauver($donnees, $id = null, $tags = array(), $duree_de_vie_specifique = false) {$resultat = true;if ($this->options['mise_en_cache'] === true) {$id = ($id === null) ? $this->dernier_id : $this->prefixerId($id);self::validerIdOuTag($id);self::validerTableauDeTags($tags);$donnees = $this->serialiserAutomatiquement($donnees);$this->nettoyerAutomatiquement();$resultat = $this->executerMethodeStockage('sauver', array($donnees, $id, $tags, $duree_de_vie_specifique));if ($resultat == false) {// Le cache étant peut être corrompu, nous le supprimons$this->supprimer($id);} else {$resultat = $this->controlerEcriture($id, $donnees);}}return $resultat;}/*** Supprime un enregistrement en cache.** @param string $id Identificant du cache à supprimer.* @return boolean True si ok*/public function supprimer($id) {$resultat = true;if ($this->options['mise_en_cache'] === true) {$id = $this->prefixerId($id);self::validerIdOuTag($id);$resultat = $this->executerMethodeStockage('supprimer', array($id));}return $resultat;}/*** Nettoyage des enregistrements en cache** Mode de nettoyage disponibles :* 'tous' (défaut) => supprime tous les enregistrements ($tags n'est pas utilisé)* 'expiration' => supprime tous les enregistrements dont la date d'expériration est dépassée ($tags n'est pas utilisé)* 'avecLesTag' => supprime tous les enregistrements contenant tous les tags indiqués* 'sansLesTag' => supprime tous les enregistrements contenant aucun des tags indiqués* 'avecUnTag' => supprime tous les enregistrements contenant au moins un des tags indiqués** @param string $mode mode de nettoyage* @param array|string $tags peut être un tableau de chaîne ou une simple chaine.* @return boolean True si ok*/public function nettoyer($mode = self::NETTOYAGE_MODE_TOUS, $tags = array()) {$resultat = true;if ($this->options['mise_en_cache'] === true) {if (!in_array($mode, array(Cache::NETTOYAGE_MODE_TOUS,Cache::NETTOYAGE_MODE_EXPIRATION,Cache::NETTOYAGE_MODE_AVEC_LES_TAGS,Cache::NETTOYAGE_MODE_SANS_LES_TAGS,Cache::NETTOYAGE_MODE_AVEC_UN_TAG))) {trigger_error("Le mode de nettoyage du cache indiqué n'est pas valide", E_USER_WARNING);}self::validerTableauDeTags($tags);$resultat = $this->executerMethodeStockage('nettoyer', array($mode, $tags));}return $resultat;}/*** Return an array of stored cache ids** @return array array of stored cache ids (string)*/public function getIds() {$ids = $this->executerMethodeStockage('getIds');$ids = $this->supprimerPrefixe($ids);return $ids;}/*** Return an array of stored tags** @return array array of stored tags (string)*/public function getTags() {return $this->executerMethodeStockage('getTags');}/*** Return an array of stored cache ids which match given tags** In case of multiple tags, a logical AND is made between tags** @param array $tags array of tags* @return array array of matching cache ids (string)*/public function getIdsAvecLesTags($tags = array()) {$ids = $this->executerMethodeStockage('getIdsAvecLesTags', array($tags));$ids = $this->supprimerPrefixe($ids);return $ids;}/*** Return an array of stored cache ids which don't match given tags** In case of multiple tags, a logical OR is made between tags** @param array $tags array of tags* @return array array of not matching cache ids (string)*/public function getIdsSansLesTags($tags = array()) {$ids = $this->executerMethodeStockage('getIdsSansLesTags', array($tags));$ids = $this->supprimerPrefixe($ids);return $ids;}/*** Return an array of stored cache ids which match any given tags** In case of multiple tags, a logical OR is made between tags** @param array $tags array of tags* @return array array of matching any cache ids (string)*/public function getIdsAvecUnTag($tags = array()) {$ids = $this->executerMethodeStockage('getIdsAvecUnTag', array($tags));$ids = $this->supprimerPrefixe($ids);return $ids;}/*** Return the filling percentage of the backend storage** @return int integer between 0 and 100*/public function getPourcentageRemplissage() {return $this->executerMethodeStockage('getPourcentageRemplissage');}/*** Return an array of metadatas for the given cache id** The array will include these keys :* - expire : the expire timestamp* - tags : a string array of tags* - mtime : timestamp of last modification time** @param string $id cache id* @return array array of metadatas (false if the cache id is not found)*/public function getMetadonnees($id) {$id = $this->prefixerId($id);return $this->executerMethodeStockage('getMetadonnees', array($id));}/*** Give (if possible) an extra lifetime to the given cache id** @param string $id cache id* @param int $extraLifetime* @return boolean true if ok*/public function ajouterSupplementDureeDeVie($id, $supplement_duree_de_vie) {$id = $this->prefixerId($id);return $this->executerMethodeStockage('ajouterSupplementDureeDeVie', array($id, $supplement_duree_de_vie));}/*** Fabrique et retourne l'identifiant du cache avec son préfixe.** Vérifie l'option 'cache_id_prefixe' et retourne le nouvel id avec préfixe ou simplement l'id lui même si elle vaut null.** @param string $id Identifiant du cache.* @return string Identifiant du cache avec ou sans préfixe.*/private function prefixerId($id) {$nouvel_id = $id;if (($id !== null) && isset($this->options['cache_id_prefixe'])) {$nouvel_id = $this->options['cache_id_prefixe'].$id;}return $nouvel_id;}private function executerMethodeStockage($methode, $params = null) {if (method_exists($this->stockage, $methode)) {if ($params == null) {$resultat = call_user_func(array($this->stockage, $methode));} else {$resultat = call_user_func_array(array($this->stockage, $methode), $params);}} else {$resultat = false;trigger_error("La méthode '$methode' n'existe pas dans la classe '".get_class($this)."'.", E_USER_WARNING);}return $resultat;}private function supprimerPrefixe($ids) {// Il est nécessaire de retirer les cache_id_prefixe des ids (voir #ZF-6178, #ZF-7600)if (isset($this->options['cache_id_prefixe']) && $this->options['cache_id_prefixe'] !== '') {$prefixe =& $this->options['cache_id_prefixe'];$prefixe_longueur = strlen($prefixe);foreach ($ids as &$id) {if (strpos($id, $prefixe) === 0) {$id = substr($id, $prefixe_longueur);}}}return $ids;}private function controlerEcriture($id, $donnees_avant_ecriture) {$resultat = true;if ($this->options['controle_ecriture']) {$donnees_apres_ecriture = $this->executerMethodeStockage('charger', array($id, true));if ($donnees_avant_ecriture != $donnees_apres_ecriture) {$this->executerMethodeStockage('supprimer', array($id));$resultat = false;}}return $resultat;}private function deserialiserAutomatiquement($donnees) {if ($donnees !== false && $this->options['serialisation_auto']) {// we need to unserialize before sending the result$donnees = unserialize($donnees);}return $donnees;}private function serialiserAutomatiquement($donnees) {if ($this->options['serialisation_auto']) {// we need to serialize datas before storing them$donnees = serialize($donnees);} else {if (!is_string($donnees)) {trigger_error("Les données doivent être une chaîne de caractères ou vous devez activez l'option serialisation_auto = true", E_USER_WARNING);}}return $donnees;}private function nettoyerAutomatiquement() {if ($this->options['nettoyage_auto'] > 0) {$rand = rand(1, $this->options['nettoyage_auto']);if ($rand == 1) {$this->nettoyer(self::NETTOYAGE_MODE_EXPIRATION);}}}/*** Valide un identifiant de cache ou un tag (securité, nom de fichiers fiables, préfixes réservés...)** @param string $chaine Identificant de cache ou tag* @return void*/protected static function validerIdOuTag($chaine) {if (!is_string($chaine)) {trigger_error('Id ou tag invalide : doit être une chaîne de caractères', E_USER_ERROR);}if (substr($chaine, 0, 9) == 'internal-') {trigger_error('"internal-*" identifiants ou tags sont réservés', E_USER_WARNING);}if (!preg_match('~^[a-zA-Z0-9_]+$~D', $chaine)) {trigger_error("Id ou tag invalide '$chaine' : doit contenir seulement [a-zA-Z0-9_]", E_USER_WARNING);}}/*** Valide un tableau de tags (securité, nom de fichiers fiables, préfixes réservés...)** @param array $tags tableau de tags* @return void*/protected static function validerTableauDeTags($tags) {if (!is_array($tags)) {trigger_error("Tableau de tags invalide : doit être un tableau 'array'", E_USER_WARNING);}foreach ($tags as $tag) {self::validerIdOuTag($tag);}reset($tags);}/*** Calcule et retourne le timestamp d'expiration** @return int timestamp d'expiration (unix timestamp)*/public function getTimestampExpiration($duree_de_vie) {if ($duree_de_vie === false) {if (isset($this->options['duree_de_vie']) && is_int($this->options['duree_de_vie'])) {$duree_de_vie = (int) $this->options['duree_de_vie'];} else {$duree_de_vie = 3600;}}$timestamp = ($duree_de_vie === null) ? 9999999999 : (time() + $duree_de_vie);return $timestamp;}}