Subversion Repositories Applications.framework

Rev

Rev 248 | Rev 282 | Go to most recent revision | Details | Compare with Previous | Last modification | View Log | RSS feed

Rev Author Line No. Line
246 jpm 1 
<?php
2 
// declare(encoding='UTF-8');
3 
/**
4 
 * Classe Cache permettant de mettre en cache des données.
5 
 * Basée sur les principes de Zend_Cache (Copyright (c) 2005-2010, Zend Technologies USA, Inc. All rights reserved.)
6 
 *
7 
 * @category	php 5.2
8 
 * @package	Framework
9 
 * @author		Jean-Pascal MILCENT <jpm@tela-botanica.org>
10 
 * @copyright	Copyright (c) 2010, Tela Botanica (accueil@tela-botanica.org)
11 
 * @license	http://framework.zend.com/license/new-bsd Licence New BSD
12 
 * @license	http://www.cecill.info/licences/Licence_CeCILL_V2-fr.txt Licence CECILL
13 
 * @license	http://www.gnu.org/licenses/gpl.html Licence GNU-GPL
14 
 * @version	$Id$
15 
 * @link		/doc/framework/
16 
 */
17 
class Cache {
18 
	/** Socke les enregistrements du cache dans des fichiers textes. */
19 
	const STOCKAGE_MODE_FICHIER = "Fichier";
20 
	/** Socke les enregistrements du cache dans une base de données SQLite. */
21 
	const STOCKAGE_MODE_SQLITE = "Sqlite";
22 
 
23 
	/** 'tous' (par défaut) : supprime tous les enregistrements. */
24 
	const NETTOYAGE_MODE_TOUS = "tous";
25 
	/** 'expiration' : supprime tous les enregistrements dont la date d'expériration est dépassée. */
26 
	const NETTOYAGE_MODE_EXPIRATION = "expiration";
27 
	/** 'avecLesTags' : supprime tous les enregistrements contenant tous les tags indiqués. */
28 
	const NETTOYAGE_MODE_AVEC_LES_TAGS = "avecLesTags";
29 
	/** 'sansLesTags' : supprime tous les enregistrements contenant aucun des tags indiqués. */
30 
	const NETTOYAGE_MODE_SANS_LES_TAGS = "sansLesTags";
31 
	/** 'avecUnTag' : supprime tous les enregistrements contenant au moins un des tags indiqués. */
32 
	const NETTOYAGE_MODE_AVEC_UN_TAG = "avecUnTag";
33 
 
34 
	/**
35 
	 * Dernier identifiant de cache utilisé.
36 
	 *
37 
	 * @var string $dernier_id
38 
	 */
39 
	private $dernier_id = null;
40 
 
41 
	/**
42 
	 * Les options disponibles pour le cache :
43 
	 *
44 
	 * ====> (boolean) controle_ecriture : [write_control]
45 
	 * - Enable / disable write control (the cache is read just after writing to detect corrupt entries)
46 
	 * - Enable write control will lightly slow the cache writing but not the cache reading
47 
	 * Write control can detect some corrupt cache files but maybe it's not a perfect control
48 
	 *
49 
	 * ====> (boolean) mise_en_cache : [caching]
50 
	 * - Enable / disable caching
51 
	 * (can be very useful for the debug of cached scripts)
52 
	 *
53 
	 * =====> (string) cache_id_prefixe : [cache_id_prefix]
54 
	 * - prefix for cache ids (namespace)
55 
	 *
56 
	 * ====> (boolean) serialisation_auto : [automatic_serialization]
57 
	 * - Enable / disable automatic serialization
58 
	 * - It can be used to save directly datas which aren't strings (but it's slower)
59 
	 *
60 
	 * ====> (int) nettoyage_auto : [automatic_cleaning_factor]
61 
	 * - Disable / Tune the automatic cleaning process
62 
	 * - The automatic cleaning process destroy too old (for the given life time)
63 
	 *   cache files when a new cache file is written :
64 
	 *	 0			   => no automatic cache cleaning
65 
	 *	 1			   => systematic cache cleaning
66 
	 *	 x (integer) > 1 => automatic cleaning randomly 1 times on x cache write
67 
	 *
68 
	 * ====> (int) duree_de_vie : [lifetime]
69 
	 * - Cache lifetime (in seconds)
70 
	 * - If null, the cache is valid forever.
71 
	 *
72 
	 * @var array $options les options disponibles pour le cache .
73 
	 */
74 
	protected $options = array(
75 
		'stockage_mode'				 => self::STOCKAGE_MODE_FICHIER,
76 
		'stockage_chemin'				 => null,
77 
		'controle_ecriture'			 => true,
78 
		'mise_en_cache'		  		 => true,
79 
		'cache_id_prefixe'		  		 => null,
80 
		'serialisation_auto'		  	 => false,
81 
		'nettoyage_auto'				 => 10,
82 
		'duree_de_vie'			 		 => 3600,
83 
	);
84 
 
248 jpm 85 
	protected $stockage = null;
86 
 
269 jpm 87 
	public function __construct($options, $options_stockage = array()) {
248 jpm 88 
		$this->setOptions($options);
89 
		if ($this->options['stockage_mode'] == self::STOCKAGE_MODE_FICHIER) {
269 jpm 90 
			$this->stockage = new CacheFichier($options_stockage, $this);
248 jpm 91 
		} else if ($this->options['stockage_mode'] == self::STOCKAGE_MODE_SQLITE) {
269 jpm 92 
			$this->stockage = new CacheSqlite($options_stockage, $this);
248 jpm 93 
		}
94 
		$this->stockage->setEmplacement($this->options['stockage_chemin']);
246 jpm 95 
	}
96 
 
248 jpm 97 
	private function setOptions($options) {
98 
		while (list($nom, $valeur) = each($options)) {
99 
			if (!is_string($nom)) {
100 
				trigger_error("Nom d'option incorecte : $nom", E_USER_WARNING);
101 
			}
102 
			$nom = strtolower($nom);
103 
			if (array_key_exists($nom, $this->options)) {
104 
				$this->options[$nom] = $valeur;
105 
			}
246 jpm 106 
		}
107 
	}
108 
 
109 
	/**
110 
	 * Permet de (re-)définir l'emplacement pour le stockage du cache.
111 
	 * En fonction du mode de stockage utilisé , l'emplacement indiqué correspondra au chemin du :
112 
	 *  - dossier où stocker les fichiers pour le mode "fichier".
113 
	 *  - fichier de la base de données pour le mode "sqlite".
114 
	 * @param string $emplacement chemin vers dossier (Cache::STOCKAGE_MODE_FICHIER) ou fichier base Sqlite (Cache::STOCKAGE_MODE_SQLITE)
115 
	 * @return void
116 
	 */
117 
	public function setEmplacement($emplacement) {
118 
		if ($emplacement != null) {
119 
			$this->executerMethodeStockage('setEmplacement', array($emplacement));
120 
		} else {
248 jpm 121 
			trigger_error("L'emplacement ne peut pas être null.", E_USER_WARNING);
246 jpm 122 
		}
123 
	}
124 
 
125 
	/**
126 
	 * Teste si un cache est disponible pour l'identifiant donné et (si oui) le retourne (false dans le cas contraire)
127 
	 *
128 
	 * @param  string  $id Identifiant de cache.
129 
	 * @param  boolean $ne_pas_tester_validiter_du_cache Si mis à true, la validité du cache n'est pas testée
130 
	 * @return mixed|false Cached datas
131 
	 */
132 
	public function charger($id, $ne_pas_tester_validiter_du_cache = false) {
133 
		$donnees = false;
134 
		if ($this->options['mise_en_cache'] === true) {
248 jpm 135 
			$id = $this->prefixerId($id);
246 jpm 136 
			$this->dernier_id = $id;
137 
			self::validerIdOuTag($id);
138 
			$donnees = $this->executerMethodeStockage('charger', array($id, $ne_pas_tester_validiter_du_cache));
139 
			$donnees = $this->deserialiserAutomatiquement($donnees);
140 
		}
141 
		return $donnees;
142 
	}
143 
 
144 
	/**
248 jpm 145 
	 * Test if a cache is available for the given id
146 
	 *
147 
	 * @param  string $id Cache id
148 
	 * @return int|false Last modified time of cache entry if it is available, false otherwise
149 
	 */
150 
	public function tester($id) {
151 
		$resultat = false;
152 
		if ($this->options['mise_en_cache'] === true) {
153 
		  	$id = $this->prefixerId($id);
154 
			self::validerIdOuTag($id);
155 
			$this->dernier_id = $id;
156 
			$resultat = $this->executerMethodeStockage('tester', array($id));
157 
		}
158 
		return $resultat;
159 
	}
160 
 
161 
	/**
246 jpm 162 
	 * Sauvegarde en cache les données passées en paramètre.
163 
	 *
164 
	 * @param  mixed $donnees Données à mettre en cache (peut être différent d'une chaine si serialisation_auto vaut true).
165 
	 * @param  string $id	 Identifiant du cache (s'il n'est pas définit, le dernier identifiant sera utilisé).
166 
	 * @param  array $tags Mots-clés du cache.
167 
	 * @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)
168 
	 * @return boolean True si aucun problème n'est survenu.
169 
	 */
170 
	public function sauver($donnees, $id = null, $tags = array(), $duree_de_vie_specifique = false) {
171 
		$resultat = true;
172 
		if ($this->options['mise_en_cache'] === true) {
248 jpm 173 
			$id = ($id === null) ? $this->dernier_id : $this->prefixerId($id);
246 jpm 174 
 
175 
			self::validerIdOuTag($id);
176 
			self::validerTableauDeTags($tags);
177 
			$donnees = $this->serialiserAutomatiquement($donnees);
178 
			$this->nettoyerAutomatiquement();
179 
 
180 
			$resultat = $this->executerMethodeStockage('sauver', array($donnees, $id, $tags, $duree_de_vie_specifique));
181 
 
182 
			if ($resultat == false) {
183 
				// Le cache étant peut être corrompu, nous le supprimons
184 
				$this->supprimer($id);
185 
			} else {
186 
				$resultat = $this->controlerEcriture($id, $donnees);
187 
			}
188 
		}
189 
		return $resultat;
190 
	}
191 
 
192 
	/**
248 jpm 193 
	 * Supprime un enregistrement en cache.
194 
	 *
195 
	 * @param  string $id Identificant du cache à supprimer.
196 
	 * @return boolean True si ok
197 
	 */
198 
	public function supprimer($id) {
199 
		$resultat = true;
200 
		if ($this->options['mise_en_cache'] === true) {
201 
			$id = $this->prefixerId($id);
202 
			self::validerIdOuTag($id);
203 
		   $resultat = $this->executerMethodeStockage('supprimer', array($id));
204 
		}
205 
		return $resultat;
206 
	}
207 
 
208 
	/**
246 jpm 209 
	 * Nettoyage des enregistrements en cache
210 
	 *
211 
	 * Mode de nettoyage disponibles :
212 
	 * 'tous' (défaut)	=> supprime tous les enregistrements ($tags n'est pas utilisé)
213 
	 * 'expiration'		=> supprime tous les enregistrements dont la date d'expériration est dépassée ($tags n'est pas utilisé)
214 
	 * 'avecLesTag'		=> supprime tous les enregistrements contenant tous les tags indiqués
215 
	 * 'sansLesTag'		=> supprime tous les enregistrements contenant aucun des tags indiqués
216 
	 * 'avecUnTag'			=> supprime tous les enregistrements contenant au moins un des tags indiqués
217 
	 *
218 
	 * @param string $mode mode de nettoyage
219 
	 * @param array|string $tags peut être un tableau de chaîne ou une simple chaine.
220 
	 * @return boolean True si ok
221 
	 */
222 
	public function nettoyer($mode = self::NETTOYAGE_MODE_TOUS, $tags = array()) {
223 
		$resultat = true;
224 
		if ($this->options['mise_en_cache'] === true) {
225 
			if (!in_array($mode, array(Cache::NETTOYAGE_MODE_TOUS,
226 
				Cache::NETTOYAGE_MODE_EXPIRATION,
227 
				Cache::NETTOYAGE_MODE_AVEC_LES_TAGS,
228 
				Cache::NETTOYAGE_MODE_SANS_LES_TAGS,
229 
				Cache::NETTOYAGE_MODE_AVEC_UN_TAG))) {
230 
				trigger_error("Le mode de nettoyage du cache indiqué n'est pas valide", E_USER_WARNING);
231 
			}
232 
			self::validerTableauDeTags($tags);
233 
 
234 
			$resultat = $this->executerMethodeStockage('nettoyer', array($mode, $tags));
235 
		}
236 
		return $resultat;
237 
	}
248 jpm 238 
 
239 
	/**
240 
	 * Return an array of stored cache ids
241 
	 *
242 
	 * @return array array of stored cache ids (string)
243 
	 */
244 
	public function getIds() {
245 
		$ids = $this->executerMethodeStockage('getIds');
246 
		$ids = $this->supprimerPrefixe($ids);
247 
		return $ids;
248 
	}
249 
 
250 
	/**
251 
	 * Return an array of stored tags
252 
	 *
253 
	 * @return array array of stored tags (string)
254 
	 */
255 
	public function getTags() {
256 
		return $this->executerMethodeStockage('getTags');
257 
	}
246 jpm 258 
 
248 jpm 259 
	/**
260 
	 * Return an array of stored cache ids which match given tags
261 
	 *
262 
	 * In case of multiple tags, a logical AND is made between tags
263 
	 *
264 
	 * @param array $tags array of tags
265 
	 * @return array array of matching cache ids (string)
266 
	 */
267 
	public function getIdsAvecLesTags($tags = array()) {
268 
		$ids = $this->executerMethodeStockage('getIdsAvecLesTags', array($tags));
269 
		$ids = $this->supprimerPrefixe($ids);
270 
		return $ids;
271 
	}
272 
 
273 
	/**
274 
	 * Return an array of stored cache ids which don't match given tags
275 
	 *
276 
	 * In case of multiple tags, a logical OR is made between tags
277 
	 *
278 
	 * @param array $tags array of tags
279 
	 * @return array array of not matching cache ids (string)
280 
	 */
281 
	public function getIdsSansLesTags($tags = array()) {
282 
	   	$ids = $this->executerMethodeStockage('getIdsSansLesTags', array($tags));
283 
		$ids = $this->supprimerPrefixe($ids);
284 
		return $ids;
285 
	}
286 
 
287 
	/**
288 
	 * Return an array of stored cache ids which match any given tags
289 
	 *
290 
	 * In case of multiple tags, a logical OR is made between tags
291 
	 *
292 
	 * @param array $tags array of tags
293 
	 * @return array array of matching any cache ids (string)
294 
	 */
295 
	public function getIdsAvecUnTag($tags = array()) {
296 
		$ids = $this->executerMethodeStockage('getIdsAvecUnTag', array($tags));
297 
		$ids = $this->supprimerPrefixe($ids);
298 
		return $ids;
299 
	}
300 
 
301 
	/**
302 
	 * Return the filling percentage of the backend storage
303 
	 *
304 
	 * @return int integer between 0 and 100
305 
	 */
306 
	public function getPourcentageRemplissage() {
307 
		return $this->executerMethodeStockage('getPourcentageRemplissage');
308 
	}
309 
 
310 
	/**
311 
	 * Return an array of metadatas for the given cache id
312 
	 *
313 
	 * The array will include these keys :
314 
	 * - expire : the expire timestamp
315 
	 * - tags : a string array of tags
316 
	 * - mtime : timestamp of last modification time
317 
	 *
318 
	 * @param string $id cache id
319 
	 * @return array array of metadatas (false if the cache id is not found)
320 
	 */
321 
	public function getMetadonnees($id) {
322 
		$id = $this->prefixerId($id);
323 
		return $this->executerMethodeStockage('getMetadonnees', array($id));
324 
	}
325 
 
326 
	/**
327 
	 * Give (if possible) an extra lifetime to the given cache id
328 
	 *
329 
	 * @param string $id cache id
330 
	 * @param int $extraLifetime
331 
	 * @return boolean true if ok
332 
	 */
333 
	public function ajouterSupplementDureeDeVie($id, $supplement_duree_de_vie) {
334 
		$id = $this->prefixerId($id);
335 
		return $this->executerMethodeStockage('ajouterSupplementDureeDeVie', array($id, $supplement_duree_de_vie));
336 
	}
337 
 
338 
 
339 
	/**
340 
	 * Fabrique et retourne l'identifiant du cache avec son préfixe.
341 
	 *
342 
	 * 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.
343 
	 *
344 
	 * @param  string $id Identifiant du cache.
345 
	 * @return string Identifiant du cache avec ou sans préfixe.
346 
	 */
347 
	private function prefixerId($id) {
348 
		$nouvel_id = $id;
349 
		if (($id !== null) && isset($this->options['cache_id_prefixe'])) {
350 
			$nouvel_id = $this->options['cache_id_prefixe'].$id;
246 jpm 351 
		}
248 jpm 352 
		return $nouvel_id;
353 
	}
354 
 
355 
	private function executerMethodeStockage($methode, $params = null) {
356 
		if (method_exists($this->stockage, $methode)) {
357 
			if ($params == null) {
358 
				$resultat = call_user_func(array($this->stockage, $methode));
359 
			} else {
360 
				$resultat = call_user_func_array(array($this->stockage, $methode), $params);
361 
			}
362 
		} else {
363 
			$resultat = false;
364 
			trigger_error("La méthode '$methode' n'existe pas dans la classe '".get_class($this)."'.", E_USER_WARNING);
365 
		}
246 jpm 366 
		return $resultat;
248 jpm 367 
	}
246 jpm 368 
 
248 jpm 369 
	private function supprimerPrefixe($ids) {
370 
		// Il est nécessaire de retirer les cache_id_prefixe des ids (voir #ZF-6178, #ZF-7600)
371 
		if (isset($this->options['cache_id_prefixe']) && $this->options['cache_id_prefixe'] !== '') {
372 
			$prefixe =& $this->options['cache_id_prefixe'];
373 
			$prefixe_longueur = strlen($prefixe);
374 
			foreach ($ids as &$id) {
375 
				if (strpos($id, $prefixe) === 0) {
376 
					$id = substr($id, $prefixe_longueur);
377 
				}
378 
			}
379 
		}
380 
		return $ids;
381 
	}
382 
 
246 jpm 383 
	private function controlerEcriture($id, $donnees_avant_ecriture) {
384 
		$resultat = true;
385 
		if ($this->options['controle_ecriture']) {
386 
			$donnees_apres_ecriture = $this->executerMethodeStockage('charger', array($id, true));
387 
			if ($donnees_avant_ecriture != $donnees_apres_ecriture) {
388 
				$this->executerMethodeStockage('supprimer', array($id));
389 
				$resultat = false;
390 
			}
391 
		}
392 
		return $resultat;
393 
	}
394 
 
395 
	private function deserialiserAutomatiquement($donnees) {
396 
		if ($donnees !== false && $this->options['serialisation_auto']) {
397 
				// we need to unserialize before sending the result
398 
				$donnees = unserialize($donnees);
399 
		}
400 
		return $donnees;
401 
	}
402 
 
403 
	private function serialiserAutomatiquement($donnees) {
404 
		if ($this->options['serialisation_auto']) {
405 
			// we need to serialize datas before storing them
406 
			$donnees = serialize($donnees);
407 
		} else {
408 
			if (!is_string($donnees)) {
409 
				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);
410 
			}
411 
		}
412 
		return $donnees;
413 
	}
414 
 
415 
	private function nettoyerAutomatiquement() {
416 
		if ($this->options['nettoyage_auto'] > 0) {
417 
			$rand = rand(1, $this->options['nettoyage_auto']);
418 
			if ($rand == 1) {
248 jpm 419 
				$this->nettoyer(self::NETTOYAGE_MODE_EXPIRATION);
246 jpm 420 
			}
421 
		}
422 
	}
423 
 
424 
	/**
425 
	 * Valide un identifiant de cache ou un tag (securité, nom de fichiers fiables, préfixes réservés...)
426 
	 *
427 
	 * @param  string $chaine Identificant de cache ou tag
428 
	 * @return void
429 
	 */
430 
	protected static function validerIdOuTag($chaine) {
431 
		if (!is_string($chaine)) {
248 jpm 432 
			trigger_error('Id ou tag invalide : doit être une chaîne de caractères', E_USER_ERROR);
246 jpm 433 
		}
434 
		if (substr($chaine, 0, 9) == 'internal-') {
435 
			trigger_error('"internal-*" identifiants ou tags sont réservés', E_USER_WARNING);
436 
		}
437 
		if (!preg_match('~^[a-zA-Z0-9_]+$~D', $chaine)) {
438 
			trigger_error("Id ou tag invalide '$chaine' : doit contenir seulement [a-zA-Z0-9_]", E_USER_WARNING);
439 
		}
440 
	}
441 
 
442 
	/**
443 
	 * Valide un tableau de tags  (securité, nom de fichiers fiables, préfixes réservés...)
444 
	 *
445 
	 * @param  array $tags tableau de tags
446 
	 * @return void
447 
	 */
448 
	protected static function validerTableauDeTags($tags) {
449 
		if (!is_array($tags)) {
450 
			trigger_error("Tableau de tags invalide : doit être un tableau 'array'", E_USER_WARNING);
451 
		}
452 
		foreach ($tags as $tag) {
453 
			self::validerIdOuTag($tag);
454 
		}
455 
		reset($tags);
456 
	}
457 
 
269 jpm 458 
	/**
459 
	 * Calcule et retourne le timestamp d'expiration
460 
	 *
461 
	 * @return int timestamp d'expiration (unix timestamp)
462 
	 */
463 
	public function getTimestampExpiration($duree_de_vie) {
464 
		if ($duree_de_vie === false) {
465 
			if (isset($this->options['duree_de_vie']) && is_int($this->options['duree_de_vie'])) {
466 
				$duree_de_vie = (int) $this->options['duree_de_vie'];
467 
			} else {
468 
				$duree_de_vie = 3600;
469 
			}
470 
		}
471 
		$timestamp = ($duree_de_vie === null) ? 9999999999 : (time() + $duree_de_vie);
472 
		return $timestamp;
473 
	}
246 jpm 474 
 
475 
}