<?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 de façon extremement simple. */
	const STOCKAGE_MODE_SIMPLE = "FichierSimple";
	/** 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 :
	 * ====> (string) stockage_mode :
	 * Indique le mode de stockage du cache à utiliser parmis :
	 * - Cache::STOCKAGE_MODE_FICHIER : sous forme d'une arborescence de fichiers et dossier
	 * - Cache::STOCKAGE_MODE_SQLITE : sous forme d'une base de données SQLite
	 * 
	 * ====> (string) stockage_chemin :
	 * Chemin vers :
	 * - Cache::STOCKAGE_MODE_FICHIER : le dossier devant contenir l'arborescence.
	 * - Cache::STOCKAGE_MODE_SQLITE : le fichier contenant la base SQLite.
	 * 
	 * ====> (boolean) controle_ecriture :
	 * - Active / Désactive le controle d'écriture (le cache est lue jute après l'écriture du fichier pour détecter sa corruption)
	 * - Activer le controle d'écriture ralentira légèrement l'écriture du fichier de cache mais pas sa lecture
	 * Le controle d'écriture peut détecter la corruption de fichier mais ce n'est pas un système de controle parfait.
	 *
	 * ====> (boolean) mise_en_cache :
	 * - Active / Désactive la mise en cache
	 * (peut être très utile pour le débogage des scripts utilisant le cache
	 *
	 * =====> (string) cache_id_prefixe :
	 * - préfixe pour les identifiant de cache ( = espace de nom)
	 *
	 * ====> (boolean) serialisation_auto :
	 * - Active / Désactive la sérialisation automatique
	 * - Peut être utilisé pour sauver directement des données qui ne sont pas des chaines (mais c'est plus lent)
	 *
	 * ====> (int) nettoyage_auto :
	 * - Désactive / Régler le processus de nettoyage automatique
	 * - Le processus de nettoyage automatiques détruit les fichier trop vieux (pour la durée de vie donnée)
	 *   quand un nouveau fichier de cache est écrit :
	 *	 0			   => pas de nettoyage automatique
	 *	 1			   => nettoyage automatique systématique
	 *	 x (integer) > 1 => nettoyage automatique toutes les 1 fois (au hasard) sur x écriture de fichier de cache
	 *
	 * ====> (int) duree_de_vie :
	 * - Durée de vie du cache (en secondes)
	 * - Si null, le cache est valide indéfiniment.
	 *
	 * @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 = array(), $options_stockage = array()) {
		$this->initialiserOptionsParConfig();
		$this->setOptions($options);
		if ($this->options['stockage_mode'] == self::STOCKAGE_MODE_FICHIER) {
			$this->stockage = new CacheFichier($options_stockage, $this);
			$this->stockage->setEmplacement($this->options['stockage_chemin']);
		} else if ($this->options['stockage_mode'] == self::STOCKAGE_MODE_SQLITE) {
			$this->stockage = new CacheSqlite($options_stockage, $this);
			$this->stockage->setEmplacement($this->options['stockage_chemin']);
		} else {
			trigger_error("Ce mode de stockage n'existe pas ou ne supporte pas la création par le constructeur", E_USER_WARNING);
		}
	}
	
	private function initialiserOptionsParConfig() {
		while (list($nom, $valeur) = each($this->options)) {
			if (Config::existe($nom)) {
				$this->options[$nom] = Config::get($nom);
			}
		}
	}
	
	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);
		}
	}
	
	public static function fabriquer($mode, $options = array()) {
		if ($mode == self::STOCKAGE_MODE_SIMPLE) {
			return new CacheSimple($options);
		} else {
			trigger_error("Le mode '$mode' de stockage n'existe pas ou ne supporte pas la création par fabrique", E_USER_WARNING);
		}
		return false;
	}
	
	/**
	 * 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;
	}
	
}