Rev 269 | 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,);public function __construct($options) {}/*** Fabrique et retourne l'identifiant du cache.** 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.*/protected function getId($id) {$nouvel_id = $id;if (($id !== null) && isset($this->options['cache_id_prefixe'])) {$nouvel_id = $this->options['cache_id_prefixe'] . $id;}return $nouvel_id;}/*** 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);}}private function setEmplacementFichier($emplacement) {if (!is_dir($emplacement)) {trigger_error("L'emplacement doit être un dossier.", E_USER_WARNING);}if (!is_writable($emplacement)) {trigger_error("Le dossier de stockage du cache n'est pas accessible en écriture", E_USER_WARNING);}$emplacement = rtrim(realpath($emplacement), '\\/').DS;$this->options['stockage_chemin'] = $emplacement;}private function setEmplacementSqlite($emplacement) {if (!extension_loaded('sqlite')) {trigger_error("Impossible d'utiliser le mode de sotckage SQLite car l'extenssion 'sqlite' n'est pas chargé dans "."l'environnement PHP courrant.\n Le mode de stockage par fichier sera utilisé à la place.");$emplacement = rtrim(realpath($emplacement), '\\/').DS;$this->options['stockage_mode'] = self::STOCKAGE_MODE_FICHIER;}$this->options['stockage_chemin'] = $emplacement;}private function executerMethodeStockage($prefixe, $params) {$methode = 'sauver'.$this->options['mode_stockage'];if (method_exists($this, $methode)) {$resultat = call_user_func_array(array($this, $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;}/*** 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->getId($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;}/*** 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->getId($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;}/*** 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;}/*** 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->getId($id);self::validerIdOuTag($id);$resultat = $this->executerMethodeStockage('supprimer', array($id));}return $resultat;}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->clean(self::NETTOYAGE_MODE_EXPIRER);}}}/*** 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_WARNING);}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);}}