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

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

PHPdoc

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