Subversion Repositories Applications.framework

<?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) {

		$this->setOptions($options);

		if ($this->options['stockage_mode'] == self::STOCKAGE_MODE_FICHIER) {

			$this->stockage = new CacheFichier($options_stockage);

		} else if ($this->options['stockage_mode'] == self::STOCKAGE_MODE_SQLITE) {

			$this->stockage = new CacheSqlite($options_stockage);

		}

		$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);

	}

}