source: spip-zone/_plugins_/cache/trunk/inc/cache_api.php @ 113747

Last change on this file since 113747 was 113747, checked in by eric@…, 20 months ago

PHPDoc la suite et pas la fin.

  • Property svn:eol-style set to native
File size: 12.6 KB
Line 
1<?php
2/**
3 * Ce fichier contient les fonctions d'API de gestion des caches.
4 *
5 * @package SPIP\CACHE\API
6 */
7if (!defined('_ECRIRE_INC_VERSION')) {
8        return;
9}
10
11
12/**
13 * Ecrit un contenu dans un cache spécifié par son identifiant.
14 *
15 * @api
16 *
17 * @uses cache_cache_configurer()
18 * @uses cache_cache_nommer()
19 *
20 * @param string        $plugin
21 *        Identifiant qui permet de distinguer le module appelant qui peut-être un plugin comme le noiZetier
22 *        ou un script. Pour un plugin, le plus pertinent est d'utiliser le préfixe.
23 * @param array|string  $cache
24 *        Identifiant du cache sous la forme d'une chaine (le chemin du fichier) ou d'un tableau fournissant
25 *        les composants canoniques du nom.
26 * @param array|string  $contenu
27 *        Contenu sous forme de tableau à sérialiser ou sous la forme d'une chaine.
28 *
29 * @return bool
30 *         True si l'écriture s'est bien passée, false sinon.
31 */
32function cache_ecrire($plugin, $cache, $contenu) {
33
34        // Initialisation du retour de la fonction
35        $cache_ecrit = false;
36       
37        // Lecture de la configuration des caches du plugin.
38        // Si celle-ci n'existe pas encore elle est créée (cas d'un premier appel).
39        static $configuration = array();
40        if (empty($configuration[$plugin]) and (!$configuration[$plugin] = cache_configuration_lire($plugin))) {
41                $configuration[$plugin] = cache_cache_configurer($plugin);
42        }
43       
44        // Le cache peut-être fourni soit sous la forme d'un chemin complet soit sous la forme d'un
45        // tableau permettant de calculer le chemin complet. On prend en compte ces deux cas.
46        $fichier_cache = '';
47        if (is_array($cache)) {
48                // Création du répertoire du cache à créer, si besoin.
49                if (!empty($cache['sous_dossier'])) {
50                        // Si le conteneur nécessite un sous-dossier, appelé service dans l'identifiant du conteneur.
51                        sous_repertoire($configuration[$plugin]['dossier_base'], rtrim($cache['sous_dossier'], '/'));
52                }
53
54                // Détermination du chemin du cache :
55                // - le nom sans extension est construit à partir des éléments fournis sur le conteneur et
56                //   de la configuration du nom pour le plugin.
57                $fichier_cache = cache_cache_nommer($plugin, $cache, $configuration[$plugin])) {
58        } elseif (is_string($cache)) {
59                // Le chemin complet du fichier cache est fourni. Aucune vérification ne peut être faite
60                // il faut donc que l'appelant ait utilisé l'API cache_existe() pour calculer le fichier au préalable.
61                $fichier_cache = $cache;
62        }
63       
64        if ($fichier_cache) {
65                // Suivant que la configuration demande un sérialisation ou pas, on vérife le format du contenu
66                // de façon à toujours écrire une chaine.
67                $contenu_cache = '';
68                if ($configuration[$plugin]['serialisation']) {
69                        if (!is_array($contenu)) {
70                                $contenu_cache = $contenu_cache ? array($contenu_cache) : array();
71                        }
72                        $contenu_cache = serialize($contenu_cache);
73                } else {
74                        if (is_string($contenu)) {
75                                $contenu_cache = $contenu;
76                        }
77                }
78
79                // Ecriture du fichier cache sécurisé ou pas suivant la configuration.
80                include_spip('inc/flock');
81                $ecrire = 'ecrire_fichier';
82                if ($configuration[$plugin]['securisation']) {
83                        $ecrire = 'ecrire_fichier_securise';
84                }
85                $cache_ecrit = $ecrire($fichier_cache, $contenu_cache);
86        }
87       
88        return $cache_ecrit;
89}
90
91
92/**
93 * Lit le cache spécifié par son identifiant et renvoie le contenu sous forme de tableau
94 * ou de chaine éventuellement vide.
95 *
96 * @api
97 *
98 * @uses cache_cache_configurer()
99 * @uses cache_cache_nommer()
100 *
101 * @param string        $plugin
102 *        Identifiant qui permet de distinguer le module appelant qui peut-être un plugin comme le noiZetier
103 *        ou un script. Pour un plugin, le plus pertinent est d'utiliser le préfixe.
104 * @param array|string  $cache
105 *        Identifiant du cache sous la forme d'une chaine (le chemin du fichier) ou d'un tableau fournissant
106 *        les composants canoniques du nom.
107 *
108 * @return array|string|bool
109 *        Contenu du fichier sous la forme d'un tableau, d'une chaine ou false si une erreur s'est produite.
110 */
111function cache_lire($plugin, $cache) {
112
113        // Initialisation du contenu du cache
114        $cache_lu = false;
115       
116        // Lecture de la configuration des caches du plugin.
117        // Si celle-ci n'existe pas encore elle est créée (cas d'un premier appel, peu probable pour une lecture).
118        static $configuration = array();
119        if (empty($configuration[$plugin]) and (!$configuration[$plugin] = cache_configuration_lire($plugin))) {
120                $configuration[$plugin] = cache_cache_configurer($plugin);
121        }
122
123        // Le cache peut-être fourni soit sous la forme d'un chemin complet soit sous la forme d'un
124        // tableau permettant de calculer le chemin complet. On prend en compte ces deux cas.
125        $fichier_cache = '';
126        if (is_array($cache)) {
127                // Détermination du chemin du cache :
128                // - le nom sans extension est construit à partir des éléments fournis sur le conteneur et
129                //   de la configuration du nom pour le plugin.
130                $fichier_cache = cache_cache_nommer($plugin, $cache, $configuration[$plugin])) {
131        } elseif (is_string($cache)) {
132                // Le chemin complet du fichier cache est fourni. Aucune vérification ne peut être faite
133                // il faut donc que l'appelant ait utilisé l'API cache_existe() pour calculer le fichier au préalable.
134                $fichier_cache = $cache;
135        }
136
137        // Détermination du nom du cache en fonction du plugin appelant et du type
138        if ($fichier_cache) {
139                // Lecture du fichier cache sécurisé ou pas suivant la configuration.
140                include_spip('inc/flock');
141                $lire = 'lire_fichier';
142                if ($configuration[$plugin]['securisation']) {
143                        $lire = 'lire_fichier_securise';
144                }
145                $contenu_cache = '';
146                $lecture_ok = $lire($fichier_cache, $contenu_cache);
147               
148                if ($lecture_ok) {
149                        if ($configuration[$plugin]['serialisation']) {
150                                $cache_lu = unserialize($contenu_cache);
151                        } else {
152                                $cache_lu = $contenu_cache;
153                        }
154                }
155        }
156
157        return $cache_lu;
158}
159
160
161/**
162 * Teste l'existence d'un cache sur le disque et, si il existe, renvoie le chemin complet.
163 *
164 * @api
165 *
166 * @uses cache_cache_configurer()
167 * @uses cache_cache_nommer()
168 *
169 * @param string        $plugin
170 *        Identifiant qui permet de distinguer le module appelant qui peut-être un plugin comme le noiZetier
171 *        ou un script. Pour un plugin, le plus pertinent est d'utiliser le préfixe.
172 * @param array|string  $cache
173 *        Identifiant du cache sous la forme d'une chaine (le chemin du fichier) ou d'un tableau fournissant
174 *        les composants canoniques du nom.
175 *
176 * @return string
177 */
178function cache_existe($plugin, $cache) {
179
180        // Lecture de la configuration des caches du plugin.
181        // Si celle-ci n'existe pas encore elle est créée (cas d'un premier appel).
182        static $configuration = array();
183        if (empty($configuration[$plugin]) and (!$configuration[$plugin] = cache_configuration_lire($plugin))) {
184                $configuration[$plugin] = cache_cache_configurer($plugin);
185        }
186
187        // Le cache peut-être fourni soit sous la forme d'un chemin complet soit sous la forme d'un
188        // tableau permettant de calculer le chemin complet. On prend en compte ces deux cas.
189        $fichier_cache = '';
190        if (is_array($cache)) {
191                // Détermination du chemin du cache :
192                // - le nom sans extension est construit à partir des éléments fournis sur le conteneur et
193                //   de la configuration du nom pour le plugin.
194                $fichier_cache = cache_cache_nommer($plugin, $cache, $configuration[$plugin])) {
195        } elseif (is_string($cache)) {
196                // Le chemin complet du fichier cache est fourni. Aucune vérification ne peut être faite
197                // il faut donc que l'appelant ait utilisé l'API cache_existe() pour calculer le fichier au préalable.
198                $fichier_cache = $cache;
199        }
200
201        // Vérifier l'existence du fichier.
202        if ($fichier_cache) {
203                if (!file_exists($fichier_cache)) {
204                        $fichier_cache = '';
205                }
206        }
207
208        return $fichier_cache;
209}
210
211
212/**
213 * Renvoie le chemin complet du cache sans tester son existence.
214 * Cette fonction est une encapsulation du service cache_cache_nommer().
215 *
216 * @api
217 *
218 * @uses cache_cache_nommer()
219 *
220 * @param string $plugin
221 *        Identifiant qui permet de distinguer le module appelant qui peut-être un plugin comme le noiZetier
222 *        ou un script. Pour un plugin, le plus pertinent est d'utiliser le préfixe.
223 * @param array  $cache
224 *        Identifiant du cache sous la forme d'un tableau fournissant les composants canoniques du nom.
225 *
226 * @return string
227 */
228function cache_nommer($plugin, $cache) {
229
230        // Lecture de la configuration des caches du plugin.
231        // Si celle-ci n'existe pas encore elle est créée (cas d'un premier appel).
232        static $configuration = array();
233        if (empty($configuration[$plugin]) and (!$configuration[$plugin] = cache_configuration_lire($plugin))) {
234                $configuration[$plugin] = cache_cache_configurer($plugin);
235        }
236
237        // Le cache est toujours fourni sous la forme d'un tableau permettant de calculer le chemin complet.
238        $fichier_cache = '';
239        if (is_array($cache)) {
240                // Détermination du chemin du cache :
241                // - le nom sans extension est construit à partir des éléments fournis sur le conteneur et
242                //   de la configuration du nom pour le plugin.
243                $fichier_cache = cache_cache_nommer($plugin, $cache, $configuration[$plugin])) {
244        }
245
246        return $fichier_cache;
247}
248
249
250/**
251 * Supprime le cache spécifié par son identifiant.
252 *
253 * @api
254 *
255 * @uses cache_cache_configurer()
256 * @uses cache_cache_nommer()
257 * @uses supprimer_fichier()
258 *
259 * @param string        $plugin
260 *        Identifiant qui permet de distinguer le module appelant qui peut-être un plugin comme le noiZetier
261 *        ou un script. Pour un plugin, le plus pertinent est d'utiliser le préfixe.
262 * @param array|string  $cache
263 *        Identifiant du cache sous la forme d'une chaine (le chemin du fichier) ou d'un tableau fournissant
264 *        les composants canoniques du nom.
265 *
266 * @return bool
267 *         True si la suppression s'est bien passée, false sinon.
268 */
269function cache_supprimer($plugin, $cache) {
270
271        // Initialisation du contenu du cache
272        $cache_supprime = false;
273       
274        // Lecture de la configuration des caches du plugin.
275        // Si celle-ci n'existe pas encore elle est créée (cas d'un premier appel, peu probable pour une lecture).
276        static $configuration = array();
277        if (empty($configuration[$plugin]) and (!$configuration[$plugin] = cache_configuration_lire($plugin))) {
278                $configuration[$plugin] = cache_cache_configurer($plugin);
279        }
280
281        // Le cache peut-être fourni soit sous la forme d'un chemin complet soit sous la forme d'un
282        // tableau permettant de calculer le chemin complet. On prend en compte ces deux cas.
283        $fichier_cache = '';
284        if (is_array($cache)) {
285                // Détermination du chemin du cache :
286                // - le nom sans extension est construit à partir des éléments fournis sur le conteneur et
287                //   de la configuration du nom pour le plugin.
288                $fichier_cache = cache_cache_nommer($plugin, $cache, $configuration[$plugin])) {
289        } elseif (is_string($cache)) {
290                // Le chemin complet du fichier cache est fourni. Aucune vérification ne peut être faite
291                // il faut donc que l'appelant ait utilisé l'API cache_existe() pour calculer le fichier au préalable.
292                $fichier_cache = $cache;
293        }
294
295        // Détermination du nom du cache en fonction du plugin appelant et du type
296        if ($fichier_cache) {
297                // Lecture du fichier cache sécurisé ou pas suivant la configuration.
298                include_spip('inc/flock');
299                $cache_supprime = supprimer_fichier($fichier_cache);
300        }
301
302        return $cache_supprime;
303}
304
305
306/**
307 * Supprime le ou les caches spécifiés d'un plugin donné.
308 * A AMELIORER
309 *
310 * @api
311 *
312 * @param string $plugin
313 *        Identifiant qui permet de distinguer le module appelant qui peut-être un plugin comme le noiZetier
314 *        ou un script. Pour un plugin, le plus pertinent est d'utiliser le préfixe.
315 * @param string $nom_cache
316 *        Nom et extension du fichier cache.
317 *
318 * @return void
319 */
320function cache_vider($plugin, $caches = array()) {
321
322        // Initialisation du retour
323        $cache_vide = false;
324
325        if ($caches) {
326                $fichiers_cache = is_string($caches) ? array($caches) : $caches;
327                include_spip('inc/flock');
328                foreach ($fichiers_cache as $_fichier) {
329                        supprimer_fichier($_fichier);
330                }
331                $cache_vide = true;
332        }
333       
334        return $cache_vide;
335}
336
337
338/**
339 * Lit la configuration standard des caches d'un plugin utilisateur.
340 *
341 * @api
342 *
343 * @param string $plugin
344 *        Identifiant qui permet de distinguer le module appelant qui peut-être un plugin comme le noiZetier
345 *        ou un script. Pour un plugin, le plus pertinent est d'utiliser le préfixe.
346 *
347 * @return array
348 *        Tableau de configuration des caches d'un plugin utilisateur ou tableau vide si aucune configuration n'est encore
349 *        enregistrée.
350 */
351function cache_configuration_lire($plugin) {
352
353        // Initialisation de la configuration à retourner
354        $configuration_lue = array();
355
356        if ($plugin) {
357                // Récupération de la meta du plugin Cache
358                include_spip('inc/config');
359                $configuration_lue = lire_config("cache/${plugin}", array());
360        }
361
362        return $configuration_lue;
363}
Note: See TracBrowser for help on using the repository browser.