source: spip-zone/_plugins_/cache/trunk/cache/cache.php @ 113835

Last change on this file since 113835 was 113835, checked in by eric@…, 10 days ago

Mise à jour des services et API et début du formulaire de vidage

  • Property svn:eol-style set to native
File size: 13.8 KB
Line 
1<?php
2/**
3 * Ce fichier contient les fonctions de service du plugin Cache.
4 *
5 * Chaque fonction, soit aiguille, si elle existe, vers une fonction "homonyme" propre au plugin appelant
6 * soit déroule sa propre implémentation.
7 * Ainsi, les plugins externes peuvent, si elle leur convient, utiliser l'implémentation proposée par Cache Factory.
8 *
9 * @package SPIP\CACHE\SERVICE
10 */
11if (!defined('_ECRIRE_INC_VERSION')) {
12        return;
13}
14
15
16// -----------------------------------------------------------------------
17// ---------------------- SERVICES SURCHARGEABLES ------------------------
18// -----------------------------------------------------------------------
19
20/**
21 * Récupère la configuration des caches d'un plugin, la complète et la stocke dans une meta.
22 *
23 * Le plugin Cache Factory propose une configuration par défaut des caches.
24 *
25 * @uses cache_chercher_service()
26 * @uses sous_repertoire()
27 * @uses lire_config()
28 * @uses ecrire_config()
29 *
30 * @param string $plugin
31 *        Identifiant qui permet de distinguer le module appelant qui peut-être un plugin comme le noiZetier ou
32 *        un script. Pour un plugin, le plus pertinent est d'utiliser le préfixe.
33 *
34 * @return array
35 *        Tableau de la configuration complétée des caches d'un plugin venant d'être enregistrée.
36 */
37function cache_cache_configurer($plugin) {
38
39        // Initialisation du tableau de configuration avec les valeurs par défaut du plugin Cache.
40        $configuration_defaut = array(
41                'racine'          => _DIR_CACHE,
42                'sous_dossier'    => false,
43                'nom_obligatoire' => array('nom'),
44                'nom_facultatif'  => array(),
45                'extension'       => '.txt',
46                'securisation'    => false,
47                'serialisation'   => true,
48                'separateur'      => '_'
49        );
50
51        // Le plugin utilisateur doit fournir un service propre pour la configuration de ses caches.
52        // Cette configuration peut-être partielle, dans ce cas les données manquantes sont complétées
53        // par celles par défaut.
54        $configuration_plugin = array();
55        if ($configurer = cache_chercher_service($plugin, 'cache_configurer')) {
56                // On passe le plugin appelant à la fonction car cela permet ainsi de mutualiser les services de stockage.
57                $configuration_plugin = $configurer($plugin);
58        }
59
60        // On merge la configuration du plugin avec celle par défaut pour assure la complétude.
61        $configuration = array_merge($configuration_defaut, $configuration_plugin);
62
63        // On vérifie l'indicateur de sécurisation : si le cache doit être sécurisé alors son extension
64        // doit absolument être .php. Si ce n'est pas le cas on la force.
65        if ($configuration['securisation']
66        and ($configuration['extension'] != '.php')) {
67                $configuration['extension'] = '.php';
68        }
69
70        // Pour faciliter la construction du chemin des caches on détermine une fois pour toute le dossier
71        // de base des caches du plugin.
72        // -- Vérification de la localisation de la racine qui ne peut être que dans les trois dossiers SPIP
73        //    prévus et de la présence du / final.
74        if (!in_array($configuration['racine'], array(_DIR_CACHE, _DIR_TMP, _DIR_VAR))) {
75                $configuration['racine'] = $configuration_defaut['racine'];
76        } else {
77                // On s'assure que la racine se termine toujours par un slash.
78                $configuration['racine'] = rtrim($configuration['racine'], '/') . '/';
79        }
80
81        // -- Sous-dossier spécifique au plugin
82        $sous_dossier = ($configuration['racine'] == _DIR_VAR) ? "cache-${plugin}" : "$plugin";
83        // -- Création et enregistrement du dossier de base
84        include_spip('inc/flock');
85        $configuration['dossier_base'] = sous_repertoire($configuration['racine'], $sous_dossier);
86
87        // -- Construction du tableau des composants du nom : dans l'ordre on a toujours les composants obligatoires
88        //    suivis des composants faclutatifs.
89        $configuration['nom'] = array_merge($configuration['nom_obligatoire'], $configuration['nom_facultatif']);
90
91        // Enregistrement de la configuration du plugin utilisateur dans la meta prévue.
92        // Si une configuration existe déjà on l'écrase.
93        include_spip('inc/config');
94        $meta_cache = lire_config('cache', array());
95        $meta_cache[$plugin] = $configuration;
96        ecrire_config('cache', $meta_cache);
97
98        return $configuration;
99}
100
101
102/**
103 * Construit le chemin complet du fichier cache.
104 *
105 * @uses cache_chercher_service()
106 *
107 * @param string $plugin
108 *        Identifiant qui permet de distinguer le module appelant qui peut-être un plugin comme le noiZetier
109 *        ou un script. Pour un plugin, le plus pertinent est d'utiliser le préfixe.
110 * @param array  $cache
111 *        Tableau identifiant le cache pour lequel on veut construire le nom.
112 * @param array  $configuration
113 *        Configuration complète des caches du plugin utlisateur lue à partir de la meta de stockage.
114 *
115 * @return string
116 */
117function cache_cache_composer($plugin, $cache, $configuration) {
118
119        // Le plugin utilisateur peut fournir un service propre pour construire le chemin complet du fichier cache.
120        // Néanmoins, étant donné la généricité du mécanisme offert par le plugin Cache cela devrait être rare.
121        if ($composer = cache_chercher_service($plugin, 'cache_composer')) {
122                // On passe le plugin appelant à la fonction car cela permet ainsi de mutualiser les services de stockage.
123                $fichier_cache = $composer($plugin, $cache, $configuration);
124        } else {
125                // On utilise le mécanisme de nommage standard du plugin Cache.
126                // Initialisation du chemin complet du fichier cache
127                $fichier_cache = '';
128
129                // Détermination du répertoire final du fichier cache qui peut-être inclus dans un sous-dossier du dossier
130                // de base des caches du plugin.
131                $dir_cache = $configuration['dossier_base'];
132                if ($configuration['sous_dossier']) {
133                        if (!empty($cache['sous_dossier'])) {
134                                // Si le cache nécessite un sous-dossier, appelé service dans l'identifiant du cache.
135                                $dir_cache .= rtrim($cache['sous_dossier'], '/') . '/';
136                        } else {
137                                // C'est une erreur, le sous-dossier n'a pas été fourni alors qu'il est requis.
138                                $dir_cache = '';
139                        }
140                }
141
142                // Détermination du nom du cache sans extension.
143                // Celui-ci est construit à partir des éléments fournis sur le cache et de la configuration
144                // fournie par le plugin (liste ordonnée de composant).
145                $nom_cache = '';
146                if ($dir_cache) {
147                        foreach ($configuration['nom'] as $_composant) {
148                                if (isset($cache[$_composant])) {
149                                        $nom_cache .= ($nom_cache ? $configuration['separateur'] : '') . $cache[$_composant];
150                                }
151                        }
152                }
153
154                // Si le nom a pu être construit on finalise le chemin complet, sinon on renvoie une chaine vide.
155                if ($nom_cache) {
156                        // L'extension par défaut est dans la configuration mais peut-être forcée pour un cache donné.
157                        // Par contre, si le cache est sécurisé alors on ne tient pas compte du forçage éventuel car l'extension
158                        // doit toujours être .php et celle-ci a été forcée lors de la configuration des caches du plugin.
159                        $extension = (!empty($cache['extension']) and !$configuration['securisation'])
160                                ? $cache['extension']
161                                : $configuration['extension'];
162                        // Le chemin complet
163                        $fichier_cache = "${dir_cache}${nom_cache}${extension}";
164                }
165        }
166
167        return $fichier_cache;
168}
169
170
171/**
172 * Décompose le chemin complet du fichier cache en composants déterminé par configuration.
173 *
174 * @uses cache_chercher_service()
175 *
176 * @param string $plugin
177 *        Identifiant qui permet de distinguer le module appelant qui peut-être un plugin comme le noiZetier
178 *        ou un script. Pour un plugin, le plus pertinent est d'utiliser le préfixe.
179 * @param array  $fichier_cache
180 *        Le chemin complet du fichier à phraser.
181 * @param array  $configuration
182 *        Configuration complète des caches du plugin utlisateur lue à partir de la meta de stockage.
183 *
184 * @return array
185 *         Tableau des composants constitutifs du cache
186 */
187function cache_cache_decomposer($plugin, $fichier_cache, $configuration) {
188
189        // Le plugin utilisateur peut fournir un service propre pour construire le chemin complet du fichier cache.
190        // Néanmoins, étant donné la généricité du mécanisme offert par le plugin Cache cela devrait être rare.
191        if ($decomposer = cache_chercher_service($plugin, 'cache_decomposer')) {
192                // On passe le plugin appelant à la fonction car cela permet ainsi de mutualiser les services de stockage.
193                $cache = $decomposer($plugin, $fichier_cache, $configuration);
194        } else {
195                // On utilise le mécanisme de nommage standard du plugin Cache. De fait, on considère qu'aucun composant
196                // n'est facultatif ou du moins qu'un seul composant est facultatif et positionné en dernier.
197
198                // Initialisation du tableau cache
199                $cache = array();
200
201                // On supprime le dossier de base pour n'avoir que la partie spécifique du cache.
202                $fichier_cache = str_replace($configuration['dossier_base'], '', $fichier_cache);
203
204                // Détermination du nom du cache sans extension et décomposition suivant la configuration du nom.               
205                $nom_cache = basename($fichier_cache, $configuration['extension']);
206                foreach (explode($configuration['separateur'], $nom_cache) as $_cle => $_composant) {
207                        $cache[$configuration['nom'][$_cle]] = $_composant;
208                }
209
210                // Identification d'un sous-dossier si il existe.
211                if ($configuration['sous_dossier'] and ($sous_dossier = dirname($fichier_cache))) {
212                        $cache['sous_dossier'] = $sous_dossier;
213                }
214        }
215
216        return $cache;
217}
218
219
220/**
221 * Complète la description canonique d'un cache.
222 *
223 * Le plugin Cache Factory complète la description canonique avec le nom sans extension et l'extension du fichier.
224 *
225 * @uses cache_chercher_service()
226 *
227 * @param string $plugin
228 *        Identifiant qui permet de distinguer le module appelant qui peut-être un plugin comme le noiZetier
229 *        ou un script. Pour un plugin, le plus pertinent est d'utiliser le préfixe.
230 * @param array  $cache
231 *       Tableau identifiant le cache pour lequel on veut construire le nom.
232 * @param string $fichier_cache
233 *        Fichier cache désigné par son chemin complet.
234 * @param array  $configuration
235 *        Configuration complète des caches du plugin utlisateur lue à partir de la meta de stockage.
236 *
237 * @return array
238 *         Description du cache complétée par un ensemble de données propres au plugin.
239 */
240function cache_cache_completer($plugin, $cache, $fichier_cache, $configuration) {
241
242        // Cache Factory complète la description avec le nom sans extension et l'extension du fichier cache avant
243        // de passer la main au plugin utilisateur.
244        $cache['nom_cache'] = basename($fichier_cache, $configuration['extension']);
245        $cache['extension_cache'] = $configuration['extension'];
246
247        // Le plugin utilisateur peut fournir un service propre pour construire le chemin complet du fichier cache.
248        // Néanmoins, étant donné la généricité du mécanisme offert par le plugin Cache cela devrait être rare.
249        if ($completer = cache_chercher_service($plugin, 'cache_completer')) {
250                // On passe le plugin appelant à la fonction car cela permet ainsi de mutualiser les services de stockage.
251                $cache = $completer($plugin, $cache, $fichier_cache, $configuration);
252        }
253
254        return $cache;
255}
256
257
258/**
259 * Effectue le chargement du formulaire de vidage des caches pour un plugin utilisateur donné.
260 *
261 * Le plugin Cache Factory propose une version simplifié du formulaire où tous les fichiers caches
262 * sont listées par ordre alphabétique sans possibilité de regroupement.
263 *
264 * @uses cache_chercher_service()
265 *
266 * @param string $plugin
267 *        Identifiant qui permet de distinguer le module appelant qui peut-être un plugin comme le noiZetier
268 *        ou un script. Pour un plugin, le plus pertinent est d'utiliser le préfixe.
269 * @param array  $configuration
270 *        Configuration complète des caches du plugin utilisateur lue à partir de la meta de stockage.
271 *
272 * @return array
273 *         Description du cache complétée par un ensemble de données propres au plugin.
274 */
275function cache_cache_vider_charger($plugin, $configuration) {
276
277        // Stocker le préfixe et le nom du plugin de façon systématique.
278        $valeurs = array('_prefixe' => $plugin);
279        $informer = chercher_filtre('info_plugin');
280        $valeurs['_nom_plugin'] = $informer($plugin, 'nom', true);
281
282        // Le plugin utilisateur peut fournir un service propre pour construire le chemin complet du fichier cache.
283        // Néanmoins, étant donné la généricité du mécanisme offert par le plugin Cache cela devrait être rare.
284        if ($charger = cache_chercher_service($plugin, 'cache_vider_charger')) {
285                // On passe le plugin appelant à la fonction car cela permet ainsi de mutualiser les services de stockage.
286                $valeurs_plugin = $charger($plugin, $configuration);
287                if ($valeurs_plugin) {
288                        $valeurs = array_merge($valeurs, $valeurs_plugin);
289                }
290        } else {
291                // On présente simplement les fichiers caches en ordre alphabétique en visualisant uniquement
292                // le sous-dossuer éventuel et le nom du fichier sans décomposition.
293                $valeurs['_caches'] = cache_repertorier($plugin, array());
294        }
295
296        return $valeurs;
297}
298
299
300// -----------------------------------------------------------------------
301// ----------------- UTILITAIRE PROPRE AU PLUGIN CACHE -------------------
302// -----------------------------------------------------------------------
303
304/**
305 * Cherche une fonction donnée en se basant sur le plugin appelant.
306 * Si le plugin utilisateur ne fournit pas la fonction demandée la chaîne vide est renvoyée.
307 *
308 * @internal
309 *
310 * @param string $plugin
311 *        Identifiant qui permet de distinguer le module appelant qui peut-être un plugin comme le noiZetier ou
312 *        un script. Pour un plugin, le plus pertinent est d'utiliser le préfixe.
313 * @param bool   $fonction
314 *        Nom de la fonction de service à chercher.
315 *
316 * @return string
317 *        Nom complet de la fonction si trouvée ou chaine vide sinon.
318 */
319function cache_chercher_service($plugin, $fonction) {
320
321        $fonction_trouvee = '';
322
323        // Eviter la réentrance si on demande explicitement le service du plugin Cache.
324        if ($plugin != 'cache') {
325                include_spip("cache/${plugin}");
326                $fonction_trouvee = "${plugin}_${fonction}";
327                if (!function_exists($fonction_trouvee)) {
328                        $fonction_trouvee = '';
329                }
330        }
331
332        return $fonction_trouvee;
333}
Note: See TracBrowser for help on using the repository browser.