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

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

Mise au point du PHPDoc et de quelques items

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