Changeset 113745 in spip-zone

Timestamp:

Feb 5, 2019, 12:53:57 PM (2 months ago)

Author:

eric@…

Message:

PHPdoc

File:

• _plugins_/cache/trunk/inc/cache_api.php (modified) (7 diffs)

_plugins_/cache/trunk/inc/cache_api.php

@@ -11 +11 @@
 
 /**
- * Ecrit un contenu dans le cache spécifié d'un plugin utilisateur.
- *
- * @api
- *
- * @param string $plugin
+ * Ecrit un contenu dans un cache spécifié par son identifiant.
+ *
+ * @api
+ *
+ * @param string        $plugin
  *        Identifiant qui permet de distinguer le module appelant qui peut-être un plugin comme le noiZetier
  *        ou un script. Pour un plugin, le plus pertinent est d'utiliser le préfixe.
  * @param array|string  $cache
- *        Nom et extension du fichier cache.
- * @param array  $contenu
- *        Contenu sous forme de tableau à stocker dans un fichier cache après sérialisation.
+ *        Identifiant du cache sous la forme d'une chaine (le chemin du fichier) ou d'un tableau fournissant
+ *        les composants canoniques du nom.
+ * @param array|string  $contenu
+ *        Contenu sous forme de tableau à sérialiser ou sous la forme d'une chaine.
  *
  * @return bool
+ *         True si l'écriture s'est bien passée, false sinon.
  */
 function cache_ecrire($plugin, $cache, $contenu) {
@@ -86 +88 @@
 
 /**
- * Lit le cache spécifié d'un plugin donné et renvoie le contenu sous forme de tableau
- * éventuellement vide.
- *
- * @api
- *
- * @param string $plugin
- *        Identifiant qui permet de distinguer le module appelant qui peut-être un plugin comme le noiZetier
- *        ou un script. Pour un plugin, le plus pertinent est d'utiliser le préfixe.
- * @param array|string $cache
- *        Nom et extension du fichier cache.
+ * Lit le cache spécifié par son identifiant et renvoie le contenu sous forme de tableau
+ * ou de chaine éventuellement vide.
+ *
+ * @api
+ *
+ * @param string        $plugin
+ *        Identifiant qui permet de distinguer le module appelant qui peut-être un plugin comme le noiZetier
+ *        ou un script. Pour un plugin, le plus pertinent est d'utiliser le préfixe.
+ * @param array|string  $cache
+ *        Identifiant du cache sous la forme d'une chaine (le chemin du fichier) ou d'un tableau fournissant
+ *        les composants canoniques du nom.
  *
  * @return array|string|bool
@@ -151 +154 @@
 
 /**
- * Renvoie le chemin complet du cache si celui-ci existe sinon renvoie une chaine vide.
- *
- * @api
- *
- * @param string $plugin
- *        Identifiant qui permet de distinguer le module appelant qui peut-être un plugin comme le noiZetier
- *        ou un script. Pour un plugin, le plus pertinent est d'utiliser le préfixe.
- * @param array  $cache
- *        Tableau identifiant le cache pour lequel on veut construire le nom.
- * @param array  $configuration
- *        Configuration complète des caches du plugin utlisateur.
+ * Teste l'existence d'un cache sur le disque et, si il existe, renvoie le chemin complet.
+ *
+ * @api
+ *
+ * @param string        $plugin
+ *        Identifiant qui permet de distinguer le module appelant qui peut-être un plugin comme le noiZetier
+ *        ou un script. Pour un plugin, le plus pertinent est d'utiliser le préfixe.
+ * @param array|string  $cache
+ *        Identifiant du cache sous la forme d'une chaine (le chemin du fichier) ou d'un tableau fournissant
+ *        les composants canoniques du nom.
  *
  * @return string
@@ -200 +202 @@
 
 /**
- * Renvoie le chemin complet du cache si celui-ci existe sinon renvoie une chaine vide.
+ * Renvoie le chemin complet du cache sans tester son existence.
+ * Cette fonction est une encapsulation du service cache_cache_nommer().
  *
  * @api
@@ -208 +211 @@
  *        ou un script. Pour un plugin, le plus pertinent est d'utiliser le préfixe.
  * @param array  $cache
- *        Tableau identifiant le cache pour lequel on veut construire le nom.
- * @param array  $configuration
- *        Configuration complète des caches du plugin utlisateur.
+ *        Identifiant du cache sous la forme d'un tableau fournissant les composants canoniques du nom.
  *
  * @return string
@@ -233 +234 @@
 
         return $fichier_cache;
+}
+
+
+/**
+ * Supprime le cache spécifié par son identifiant.
+ *
+ * @api
+ *
+ * @param string        $plugin
+ *        Identifiant qui permet de distinguer le module appelant qui peut-être un plugin comme le noiZetier
+ *        ou un script. Pour un plugin, le plus pertinent est d'utiliser le préfixe.
+ * @param array|string  $cache
+ *        Identifiant du cache sous la forme d'une chaine (le chemin du fichier) ou d'un tableau fournissant
+ *        les composants canoniques du nom.
+ *
+ * @return bool
+ *         True si la suppression s'est bien passée, false sinon.
+ */
+function cache_supprimer($plugin, $cache) {
+
+        // Initialisation du contenu du cache
+        $cache_supprime = false;
+        
+        // Lecture de la configuration des caches du plugin.
+        // Si celle-ci n'existe pas encore elle est créée (cas d'un premier appel, peu probable pour une lecture).
+        static $configuration = array();
+        if (empty($configuration[$plugin]) and (!$configuration[$plugin] = cache_configuration_lire($plugin))) {
+                $configuration[$plugin] = cache_cache_configurer($plugin);
+        }
+
+        // Le cache peut-être fourni soit sous la forme d'un chemin complet soit sous la forme d'un
+        // tableau permettant de calculer le chemin complet. On prend en compte ces deux cas.
+        $fichier_cache = '';
+        if (is_array($cache)) {
+                // Détermination du chemin du cache :
+                // - le nom sans extension est construit à partir des éléments fournis sur le conteneur et
+                //   de la configuration du nom pour le plugin.
+                $fichier_cache = cache_cache_nommer($plugin, $cache, $configuration[$plugin])) {
+        } elseif (is_string($cache)) {
+                // Le chemin complet du fichier cache est fourni. Aucune vérification ne peut être faite
+                // il faut donc que l'appelant ait utilisé l'API cache_existe() pour calculer le fichier au préalable.
+                $fichier_cache = $cache;
+        }
+
+        // Détermination du nom du cache en fonction du plugin appelant et du type
+        if ($fichier_cache) {
+                // Lecture du fichier cache sécurisé ou pas suivant la configuration.
+                include_spip('inc/flock');
+                $cache_supprime = supprimer_fichier($fichier_cache);
+        }
+
+        return $cache_supprime;
 }
 
@@ -269 +322 @@
 
 /**
- * Lit la configuration des caches d'un plugin utilisateur.
+ * Lit la configuration standard des caches d'un plugin utilisateur.
  *
  * @api