source: spip-zone/_plugins_/noizetier/trunk/ncore/noizetier.php @ 113510

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

Améliorations PHPDoc

  • Property svn:eol-style set to native
File size: 28.1 KB
Line 
1<?php
2
3if (!defined('_ECRIRE_INC_VERSION')) {
4        return;
5}
6
7// -----------------------------------------------------------------------
8// ------------------------- TYPES DE NOISETTE ---------------------------
9// -----------------------------------------------------------------------
10
11/**
12 * Stocke les descriptions des types de noisette en distinguant les types de noisette obsolètes, les types de
13 * noisettes modifiés et les types de noisettes nouveaux.
14 * Chaque description de type de noisette est un tableau associatif dont tous les index possibles - y compris
15 * la signature - sont initialisés quelque soit le contenu du fichier YAML.
16 *
17 * Les types de noisettes sont stockés dans la table `spip_types_noisettes`.
18 *
19 * @package SPIP\NOIZETIER\TYPE_NOISETTE\SERVICE
20 *
21 * @param string $plugin
22 *        Identifiant qui permet de distinguer le module appelant qui peut-être un plugin comme le noiZetier ou
23 *        un script. Pour un plugin, le plus pertinent est d'utiliser le préfixe.
24 * @param array  $types_noisettes
25 *        Tableau associatif à 3 entrées fournissant les descriptions des types de noisettes nouveaux, obsolètes
26 *        et modifiés:
27 *        `a_effacer` : liste des identifiants de type de noisette devenus obsolètes.
28 *        `a_changer` : liste des descriptions des types de noisette dont le fichier YAML a été modifié.
29 *        `a_ajouter` : liste des descriptions des nouveaux types de noisette.
30 *        Si $recharger est à `true`, seul l'index `a_ajouter` est fourni dans le tableau $types_noisette.
31 * @param bool   $recharger
32 *        Indique si le chargement en cours est forcé ou pas. Cela permet à la fonction N-Core ou au service
33 *        concerné d'optimiser le traitement sachant que seules les types de noisette nouveaux sont fournis.
34 *
35 * @return bool
36 *        `true` si le traitement s'est bien déroulé, `false` sinon.
37 */
38function noizetier_type_noisette_stocker($plugin, $types_noisettes, $recharger) {
39
40        $retour = true;
41
42        // Mise à jour de la table des noisettes 'spip_types_noisettes'.
43        $from = 'spip_types_noisettes';
44
45        // -- Suppression des types de noisette obsolètes ou de tous les types de noisette d'un coup si on est en mode
46        //    rechargement forcé.
47        if (sql_preferer_transaction()) {
48                sql_demarrer_transaction();
49        }
50        $where = array('plugin=' . sql_quote($plugin));
51        if ($recharger) {
52                sql_delete($from, $where);
53        } elseif (!empty($types_noisettes['a_effacer'])) {
54                $where[] = sql_in('type_noisette', $types_noisettes['a_effacer']);
55                sql_delete($from, $where);
56        }
57        // -- Update des types de noisettes modifiés
58        if (!empty($types_noisettes['a_changer'])) {
59                sql_replace_multi($from, $types_noisettes['a_changer']);
60        }
61        // -- Insertion des nouveaux types de noisette
62        if (!empty($types_noisettes['a_ajouter'])) {
63                sql_insertq_multi($from, $types_noisettes['a_ajouter']);
64        }
65        if (sql_preferer_transaction()) {
66                sql_terminer_transaction();
67        }
68
69        return $retour;
70}
71
72/**
73 * Complète la description d'un type de noisette issue de la lecture de son fichier YAML.
74 *
75 * Le noiZetier phrase le type de noisette pour détecter son type et sa composition éventuelle.
76 *
77 * @package SPIP\NOIZETIER\TYPE_NOISETTE\SERVICE
78 *
79 * @param string $plugin
80 *        Identifiant qui permet de distinguer le module appelant qui peut-être un plugin comme le noiZetier ou
81 *        un script. Pour un plugin, le plus pertinent est d'utiliser le préfixe.
82 * @param array  $description
83 *        Description du type de noisette issue de la lecture du fichier YAML. Suivant le plugin utilisateur elle
84 *        nécessite d'être compléter avant son stockage.
85 *
86 * @return array
87 *        Description du type de noisette complétée avec le type de page et la composition (éventuellement vides).
88 */
89function noizetier_type_noisette_completer($plugin, $description) {
90
91        // Initialiser les composants de l'identifiant du type de noisette:
92        // - type_page-type_noisette si le type de noisette est dédié uniquement à une page
93        // - type_page-composition-type_noisette si le type de noisette est dédié uniquement à une composition
94        // - type_noisette sinon
95        $description['type'] = '';
96        $description['composition'] = '';
97        $identifiants = explode('-', $description['type_noisette']);
98        if (isset($identifiants[1])) {
99                $description['type'] = $identifiants[0];
100        }
101        if (isset($identifiants[2])) {
102                $description['composition'] = $identifiants[1];
103        }
104
105        return $description;
106}
107
108/**
109 * Renvoie la description brute d'un type de noisette sans traitement typo ni désérialisation des champs de type
110 * tableau sérialisé.
111 *
112 * Le noiZetier lit la description du type de noisette concerné dans la table `spip_types_noisettes`.
113 *
114 * @package SPIP\NOIZETIER\TYPE_NOISETTE\SERVICE
115 *
116 * @param string $plugin
117 *        Identifiant qui permet de distinguer le module appelant qui peut-être un plugin comme le noiZetier ou
118 *        un script. Pour un plugin, le plus pertinent est d'utiliser le préfixe.
119 * @param string $type_noisette
120 *        Identifiant du type de noisette.
121 *
122 * @return array
123 *        Tableau de la description du type de noisette. Les champs textuels et les champs de type tableau sérialisé
124 *        sont retournés en l'état, le timestamp `maj n'est pas fourni.
125 */
126function noizetier_type_noisette_decrire($plugin, $type_noisette) {
127
128        // Table des types de noisette.
129        $from = 'spip_types_noisettes';
130
131        // Chargement de toute la configuration de la noisette en base de données sauf le timestamp 'maj'.
132        // Les données sont renvoyées brutes sans traitement sur les textes ni les tableaux sérialisés.
133        $trouver_table = charger_fonction('trouver_table', 'base');
134        $table = $trouver_table($from);
135        $select = array_diff(array_keys($table['field']), array('maj'));
136
137        $where = array('plugin=' . sql_quote($plugin), 'type_noisette=' . sql_quote($type_noisette));
138        $description = sql_fetsel($select, $from, $where);
139
140        return $description;
141}
142
143/**
144 * Renvoie l'information brute demandée pour l'ensemble des types de noisette utilisés
145 * ou toute les descriptions si aucune information n'est explicitement demandée.
146 *
147 * @package SPIP\NOIZETIER\TYPE_NOISETTE\SERVICE
148 *
149 * @param string $plugin
150 *        Identifiant qui permet de distinguer le module appelant qui peut-être un plugin comme le noiZetier ou
151 *        un script. Pour un plugin, le plus pertinent est d'utiliser le préfixe.
152 * @param string $information
153 *        Identifiant d'un champ de la description d'un type de noisette.
154 *        Si l'argument est vide, la fonction renvoie les descriptions complètes et si l'argument est
155 *        un champ invalide la fonction renvoie un tableau vide.
156 *
157 * @return array
158 *        Tableau de la forme `[type_noisette] = information ou description complète`. Les champs textuels et
159 *        les champs de type tableau sérialisé sont retournés en l'état, le timestamp `maj n'est pas fourni.
160 */
161function noizetier_type_noisette_lister($plugin, $information = '') {
162
163        // Initialiser le tableau de sortie en cas d'erreur
164        $types_noisettes = array();
165
166        $from = 'spip_types_noisettes';
167        $trouver_table = charger_fonction('trouver_table', 'base');
168        $table = $trouver_table($from);
169        $champs = array_keys($table['field']);
170        if ($information) {
171                // Si une information précise est demandée on vérifie sa validité
172                $information_valide = in_array($information, $champs);
173                $select = array('type_noisette', $information);
174        } else {
175                // Tous les champs sauf le timestamp 'maj' sont renvoyés.
176                $select = array_diff($champs, array('maj'));
177        }
178        $where = array('plugin=' . sql_quote($plugin));
179
180        if ((!$information or ($information and $information_valide))
181        and ($types_noisettes = sql_allfetsel($select, $from, $where))) {
182                if ($information) {
183                        $types_noisettes = array_column($types_noisettes, $information, 'type_noisette');
184                } else {
185                        $types_noisettes = array_column($types_noisettes, null, 'type_noisette');
186                }
187        }
188
189        return $types_noisettes;
190}
191
192/**
193 * Renvoie la configuration par défaut de l'ajax à appliquer pour la compilation des noisettes.
194 * Cette information est utilisée si la description YAML d'un type noisette ne contient pas de tag ajax
195 * ou contient un tag ajax à `defaut`.
196 *
197 * @package SPIP\NOIZETIER\TYPE_NOISETTE\SERVICE
198 *
199 * @param string $plugin
200 *        Identifiant qui permet de distinguer le module appelant qui peut-être un plugin comme le noiZetier ou
201 *        un script. Pour un plugin, le plus pertinent est d'utiliser le préfixe.
202 *
203 * @return bool
204 *              `true` si par défaut une noisette est insérée en ajax, `false` sinon.
205 */
206function noizetier_type_noisette_initialiser_ajax($plugin) {
207
208        // La valeur Ajax par défaut est inscrite dans la configuration du plugin.
209        include_spip('inc/config');
210        $defaut_ajax = lire_config("${plugin}/ajax_noisette");
211
212        return $defaut_ajax;
213}
214
215
216// -----------------------------------------------------------------------
217// ----------------------------- NOISETTES -------------------------------
218// -----------------------------------------------------------------------
219
220/**
221 * Stocke la description d'une nouvelle noisette et calcule son identifiant unique, ou met à jour les paramètres
222 * d'affichage d'une noisette existante.
223 *
224 * @package SPIP\NOIZETIER\NOISETTE\SERVICE
225 *
226 * @param string $plugin
227 *        Identifiant qui permet de distinguer le module appelant qui peut-être un plugin comme le noizetier ou
228 *        un script. Pour un plugin, le plus pertinent est d'utiliser le préfixe.
229 * @param array  $description
230 *        Description de la noisette. Soit la description ne contient pas l'id de la noisette et c'est un ajout,
231 *        soit la description contient l'id et c'est une mise à jour.
232 *
233 * @return int
234 *        Id de la noisette de type entier ou 0 en cas d'erreur.
235 */
236function noizetier_noisette_stocker($plugin, $description) {
237
238        // Mise à jour en base de données.
239        if (empty($description['id_noisette'])) {
240                // On s'assure que la description contient bien le plugin et alors on insère la nouvelle noisette.
241                $id_noisette = 0;
242                if (isset($description['plugin']) and ($description['plugin'] == $plugin)) {
243                        // Insertion de la nouvelle noisette.
244                        $id_noisette = sql_insertq('spip_noisettes', $description);
245                }
246        } else {
247                // On sauvegarde l'id de la noisette et on le retire de la description pour éviter une erreur à l'update.
248                $id_noisette = intval($description['id_noisette']);
249                unset($description['id_noisette']);
250
251                // Mise à jour de la noisette.
252                $where = array('id_noisette=' . $id_noisette, 'plugin=' . sql_quote($plugin));
253                if (!sql_updateq('spip_noisettes', $description, $where)) {
254                        $id_noisette = 0;
255                }
256        }
257
258        return $id_noisette;
259}
260
261/**
262 * Transfère une noisette d'un conteneur vers un autre à un rang donné.
263 * Le rang destination n'est pas vérifié lors du rangement dans le conteneur destination. Il convient
264 * à l'appelant de vérifier que le rang est libre.
265 * La description complète de la noisette est renvoyée avec mise à jour des champs de positionnement (id_conteneur,
266 * conteneur, rang_noisette et profondeur).
267 *
268 * @param string $plugin
269 *        Identifiant qui permet de distinguer le module appelant qui peut-être un plugin comme le noiZetier ou
270 *        un script. Pour un plugin, le plus pertinent est d'utiliser le préfixe.
271 * @param array  $description
272 *        Description de la noisette à changer de conteneur.
273 * @param string $id_conteneur
274 *        Identifiant unique sous forme de chaine du conteneur destination.
275 * @param int    $rang
276 *        Rang où positionner la noisette dans le conteneur destination. Il faut toujours vérifier au préalable
277 *        que ce rang est libre.
278 * @param int    $profondeur
279 *        Profondeur de la noisette à sa nouvelle position.
280 *
281 * @return array
282 *         Description de la noisette mise à jour avec les informations sur le nouvel emplacement
283 */
284function noizetier_noisette_changer_conteneur($plugin, $description, $id_conteneur, $rang, $profondeur) {
285
286        // On rajoute la description à son emplacement destination en prenant soin de modifier les index id_conteneur,
287        // conteneur et rang_noisette qui doivent représenter le conteneur destination.
288        include_spip('inc/ncore_conteneur');
289        $description['conteneur'] = serialize(conteneur_construire($plugin, $id_conteneur));
290        $description['id_conteneur'] = $id_conteneur;
291        $description['rang_noisette'] = $rang;
292        $description['profondeur'] = $profondeur;
293
294        // On met à jour l'objet en base
295        // On sauvegarde l'id de la noisette et on le retire de la description pour éviter une erreur à l'update.
296        $id_noisette = intval($description['id_noisette']);
297        unset($description['id_noisette']);
298
299        // Mise à jour de la noisette.
300        $where = array('id_noisette=' . $id_noisette, 'plugin=' . sql_quote($plugin));
301        sql_updateq('spip_noisettes', $description, $where);
302
303        // On remet l'ide de la noisette pour renvoyer la description complète
304        $description['id_noisette'] = $id_noisette;
305
306        return $description;
307}
308
309/**
310 * Complète la description fournie avec les champs propres au noiZetier, à savoir, ceux identifiant
311 * la page/composition ou l'objet et le bloc.
312 * On parse le squelette pour identifier les données manquantes.
313 *
314 * @package SPIP\NOIZETIER\NOISETTE\SERVICE
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 array  $description
320 *        Description  par défaut de la noisette.
321 *
322 * @return array
323 *        Description de la noisette complétée avec les champs de type de page, composition, bloc et
324 *        de l'objet concerné si cela est le cas. Le champ conteneur est lui supprimé car non stocké en
325 *        base de données.
326 */
327function noizetier_noisette_completer($plugin, $description) {
328
329        if (!empty($description['conteneur'])) {
330                //
331                $complement = array(
332                        'type'        => '',
333                        'composition' => '',
334                        'objet'       => '',
335                        'id_objet'    => 0,
336                        'bloc'        => ''
337                );
338
339                // La description de la noisette contient l'id du conteneur : on le décompose car il contient certains
340                // des champs complémentaires.
341                $id_conteneur = $description['id_conteneur'];
342                $conteneur_etendu = noizetier_conteneur_decomposer($id_conteneur);
343
344                if ($conteneur_etendu) {
345                        // On ajoute les index manquants avec leur valeur par défaut
346                        $conteneur_etendu = array_merge($complement, $conteneur_etendu);
347                        // On filtre les index inutiles comme squelette par exemple.
348                        $complement = array_intersect_key($conteneur_etendu, $complement);
349                }
350
351                // Ajout du complément à la description.
352                $description = array_merge($description, $complement);
353        }
354
355        return $description;
356}
357
358/**
359 * Positionne une noisette à un rang différent que celui qu'elle occupe dans le conteneur.
360 *
361 * @package SPIP\NOIZETIER\NOISETTE\SERVICE
362 *
363 * @param string $plugin
364 *        Identifiant qui permet de distinguer le module appelant qui peut-être un plugin comme le noiZetier ou
365 *        un script. Pour un plugin, le plus pertinent est d'utiliser le préfixe.
366 * @param array  $description
367 *        Description complète de la noisette.
368 * @param int    $rang_destination
369 *        Position à laquelle ranger la noisette au sein du conteneur.
370 *
371 * @return bool
372 *        `true` si le traitement s'est bien déroulé, `false` sinon.
373 */
374function noizetier_noisette_ranger($plugin, $description, $rang_destination) {
375
376        // Initialisation de la sortie.
377        $retour = false;
378
379        if (isset($description['id_noisette']) and ($id = intval($description['id_noisette']))) {
380                $where = array('id_noisette=' . $id, 'plugin=' . sql_quote($plugin));
381                $update = array('rang_noisette' => $rang_destination);
382                if (sql_updateq('spip_noisettes', $update, $where)) {
383                        $retour = true;
384                }
385        }
386
387        return $retour;
388}
389
390/**
391 * Retire, de l'espace de stockage, une noisette donnée de son conteneur.
392 *
393 * @package SPIP\NOIZETIER\NOISETTE\SERVICE
394 *
395 * @param string       $plugin
396 *        Identifiant qui permet de distinguer le module appelant qui peut-être un plugin comme le noiZetier ou
397 *        un script. Pour un plugin, le plus pertinent est d'utiliser le préfixe.
398 * @param array|string $description
399 *        Description complète de la noisette.
400 *
401 * @return bool
402 *        `true` si le traitement s'est bien déroulé, `false` sinon.
403 */
404function noizetier_noisette_destocker($plugin, $description) {
405
406        // Initialisation de la sortie.
407        $retour = false;
408
409        // Calcul de la clause where à partir de l'id du conteneur.
410        if (isset($description['id_noisette'])) {
411                $where = array('id_noisette=' . intval($description['id_noisette']), 'plugin=' . sql_quote($plugin));
412
413                // Suppression de la noisette.
414                if (sql_delete('spip_noisettes', $where)) {
415                        $retour = true;
416                }
417        }
418
419        return $retour;
420}
421
422/**
423 * Renvoie un champ ou toute la description des noisettes d'un conteneur ou de tous les conteneurs.
424 * Le tableau retourné est indexé soit par identifiant de noisette soit par identifiant du conteneur et rang.
425 *
426 * @package SPIP\NOIZETIER\NOISETTE\SERVICE
427 *
428 * @param string $plugin
429 *        Identifiant qui permet de distinguer le module appelant qui peut-être un plugin comme le noiZetier ou
430 *        un script. Pour un plugin, le plus pertinent est d'utiliser le préfixe.
431 * @param array|string $conteneur
432 *        Tableau descriptif du conteneur ou identifiant du conteneur ou vide si on souhaite adresser tous les
433 *        conteneurs.
434 * @param string $information
435 *        Identifiant d'un champ de la description d'une type de noisette.
436 *        Si l'argument est vide, la fonction renvoie les descriptions complètes et si l'argument est
437 *        un champ invalide la fonction renvoie un tableau vide.
438 * @param string $cle
439 *        Champ de la description d'une noisette servant d'index du tableau. En général on utilisera soit `id_noisette`
440 *        soit `rang`.
441 *
442 * @return array
443 *        Tableau de la liste des informations demandées indexé par identifiant de noisette ou par rang.
444 */
445function noizetier_noisette_lister($plugin, $conteneur = array(), $information = '', $cle = 'rang_noisette') {
446
447        // Initialisation du tableau de sortie.
448        $noisettes = array();
449
450        // Construction du where et du order by en fonction du conteneur qui est soit un squelette,
451        // soit un squelette d'un objet donné, soit vide (on veut toutes les noisettes du plugin).
452        $where = array('plugin=' . sql_quote($plugin));
453        if ($conteneur) {
454                // On sélectionne le contenant par son identifiant qui est stocké dans la table.
455                if (is_array($conteneur)) {
456                        include_spip('inc/ncore_conteneur');
457                        $id_conteneur = conteneur_identifier($plugin, $conteneur);
458                } else {
459                        $id_conteneur = $conteneur;
460                }
461                $where[] = array('id_conteneur=' . sql_quote($id_conteneur));
462                $order_by = array('rang_noisette');
463        } else {
464                // On veut toutes les noisettes, on ordonne toujours le tableau résultant par conteneur et par rang dans chaque
465                // conteneur.
466                $order_by = array('id_conteneur', 'rang_noisette');
467        }
468
469        // Construction du select en fonction des informations à retourner.
470        $select = $information ? array_merge(array('id_conteneur', 'rang_noisette', 'id_noisette'), array($information)) : '*';
471
472        if ($table_noisettes = sql_allfetsel($select, 'spip_noisettes', $where, '', $order_by)) {
473                if ($cle == 'rang_noisette') {
474                        // On demande un rangement par rang.
475                        // Il faut tenir compte du fait que la liste est réduite à un conteneur ou pas.
476                        foreach ($table_noisettes as $_noisette) {
477                                if ($conteneur) {
478                                        $noisettes[$_noisette['rang_noisette']] = $information
479                                                ? array($information => $_noisette[$information])
480                                                : $_noisette;
481                                } else {
482                                        $noisettes[$_noisette['id_conteneur']][$_noisette['rang_noisette']] = $information
483                                                ? array($information => $_noisette[$information])
484                                                : $_noisette;
485                                }
486                        }
487                } else {
488                        // On demande un rangement par id_noisette
489                        $noisettes = $information
490                                ? array_column($table_noisettes, $information, 'id_noisette')
491                                : array_column($table_noisettes, null, 'id_noisette');
492                }
493        }
494
495        return $noisettes;
496}
497
498
499/**
500 * Renvoie la description brute d'une noisette sans traitement typo des champs textuels ni désérialisation
501 * des champs de type tableau sérialisé.
502 *
503 * @package SPIP\NOIZETIER\NOISETTE\SERVICE
504 *
505 * @param string $plugin
506 *        Identifiant qui permet de distinguer le module appelant qui peut-être un plugin comme le noiZetier ou
507 *        un script. Pour un plugin, le plus pertinent est d'utiliser le préfixe.
508 * @param mixed  $noisette
509 *        Identifiant de la noisette qui peut prendre soit la forme d'un entier ou d'une chaine unique, soit la forme
510 *        d'un couple (conteneur, rang).
511 *
512 * @return array
513 *        Tableau de la description du type de noisette. Les champs textuels et les champs de type tableau sérialisé
514 *        sont retournés en l'état.
515 */
516function noizetier_noisette_decrire($plugin, $noisette) {
517
518        $description = array();
519
520        $where = array();
521        if (!is_array($noisette)) {
522                // L'identifiant est l'id unique de la noisette. Il faut donc parcourir le tableau pour trouver la
523                // noisette désirée
524                // => C'est la méthode optimale pour le stockage noiZetier.
525                $where[] = 'id_noisette=' . intval($noisette);
526        } elseif (isset($noisette['id_conteneur']) and isset($noisette['rang_noisette'])) {
527                // L'identifiant est un tableau associatif fournissant l'id du conteneur et le rang.
528                $where[] = 'id_conteneur=' . sql_quote($noisette['id_conteneur']);
529                $where[] = 'rang_noisette=' . intval($noisette['rang_noisette']);
530        }
531
532        if ($where) {
533                $where[] = 'plugin=' . sql_quote($plugin);
534                $description = sql_fetsel('*', 'spip_noisettes', $where);
535        }
536
537        return $description;
538}
539
540/**
541 * Renvoie la configuration par défaut de l'encapsulation d'une noisette.
542 * Cette information est utilisée si le champ `encapsulation` de la noisette vaut `defaut`.
543 *
544 * @package SPIP\NOIZETIER\NOISETTE\SERVICE
545 *
546 * @param string $plugin
547 *        Identifiant qui permet de distinguer le module appelant qui peut-être un plugin comme le noiZetier ou
548 *        un script. Pour un plugin, le plus pertinent est d'utiliser le préfixe.
549 *
550 * @return string
551 *              Vaut `on` pour une encapsulation ou chaine vide sinon.
552 */
553function noizetier_noisette_initialiser_encapsulation($plugin) {
554
555        // La capsule par défaut est inscrite dans la configuration du plugin.
556        include_spip('inc/config');
557        $defaut_capsule = lire_config("${plugin}/encapsulation_noisette");
558
559        return $defaut_capsule;
560}
561
562
563// -----------------------------------------------------------------------
564// ----------------------------- CONTENEURS ------------------------------
565// -----------------------------------------------------------------------
566
567/**
568 * Vérifie la conformité des index du tableau représentant le conteneur et supprime les index inutiles, si besoin.
569 * Pour le noiZetier, la vérification concerne uniquement les conteneurs non noisette. Dans ce cas, le conteneur
570 * est toujours un squelette, soit générique soit d'un objet donné.
571 *
572 * @package SPIP\NOIZETIER\CONTENEUR\SERVICE
573 *
574 * @param string $plugin
575 *        Identifiant qui permet de distinguer le module appelant qui peut-être un plugin comme le noiZetier ou
576 *        un script. Pour un plugin, le plus pertinent est d'utiliser le préfixe.
577 * @param array  $conteneur
578 *        Tableau associatif descriptif du conteneur dont les index doivent être vérifiés.
579 *
580 * @return array
581 *         Tableau du conteneur dont tous les index sont conformes (`squelette` et éventuellement `objet`, `id_objet`)
582 *         ou tableau vide si non conforme.
583 */
584function noizetier_conteneur_verifier($plugin, $conteneur) {
585
586        // Liste des index autorisés.
587        static $index_conteneur = array('squelette', 'objet', 'id_objet');
588
589        // On vérifie que les index autorisés sont les seuls retournés.
590        $conteneur_verifie = array();
591        if ($conteneur) {
592                // L'index squelette doit toujours être présent.
593                if ((isset($conteneur['squelette']) and $conteneur['squelette'])) {
594                        $conteneur = array_intersect_key($conteneur, array_flip($index_conteneur));
595                        if ((count($conteneur) == 1)
596                        or ((count($conteneur) == 3)
597                                and isset($conteneur['objet'], $conteneur['id_objet'])
598                                and $conteneur['objet']
599                                and intval($conteneur['id_objet']))) {
600                                // Le conteneur coincide avec un squelette de bloc générique ou d'un objet donné.
601                                $conteneur_verifie = $conteneur;
602                        }
603                }
604        }
605
606        return $conteneur_verifie;
607}
608
609/**
610 * Construit un identifiant unique pour le conteneur de noisettes hors les noisettes conteneur.
611 * Pour le noiZetier, un conteneur est toujours un squelette, soit générique soit d'un objet donné.
612 *
613 * @package SPIP\NOIZETIER\CONTENEUR\SERVICE
614 *
615 * @param string $plugin
616 *        Identifiant qui permet de distinguer le module appelant qui peut-être un plugin comme le noiZetier ou
617 *        un script. Pour un plugin, le plus pertinent est d'utiliser le préfixe.
618 * @param array $conteneur
619 *        Tableau associatif descriptif du conteneur. Pour le noiZetier, les seuls index autorisés sont
620 *        `squelette`, `objet` et `id_objet`.
621 *
622 * @return string
623 *         L'identifiant calculé à partir du tableau.
624 */
625function noizetier_conteneur_identifier($plugin, $conteneur) {
626
627        // On initialise l'identifiant à vide.
628        $id_conteneur = '';
629
630        // Les noisettes conteneur ont été identifiées par N-Core, inutile donc de s'en préoccuper.
631        if ($conteneur) {
632                // Le nom du squelette en premier si il existe (normalement toujours).
633                if (!empty($conteneur['squelette'])) {
634                        $id_conteneur .= $conteneur['squelette'];
635                }
636                // L'objet et son id si on est en présence d'un objet.
637                if (!empty($conteneur['objet']) and !empty($conteneur['id_objet']) and intval($conteneur['id_objet'])) {
638                        $id_conteneur .= ($id_conteneur ? '|' : '') . "{$conteneur['objet']}|{$conteneur['id_objet']}";
639                }
640        }
641
642        return $id_conteneur;
643}
644
645/**
646 * Reconstruit le conteneur sous forme de tableau à partir de son identifiant unique (fonction inverse
647 * de `noizetier_conteneur_identifier`).
648 * N-Core ne fournit le conteneur pour les noisettes conteneur.
649 * Pour les autres conteneurs, c'est au noiZetier de calculer le tableau.
650 *
651 * @package SPIP\NOIZETIER\CONTENEUR\SERVICE
652 *
653 * @param string $plugin
654 *        Identifiant qui permet de distinguer le module appelant qui peut-être un plugin comme le noiZetier ou
655 *        un script. Pour un plugin, le plus pertinent est d'utiliser le préfixe.
656 * @param string $id_conteneur
657 *        Identifiant unique du conteneur.
658 *
659 * @return array
660 *        Tableau représentatif du conteneur ou tableau vide en cas d'erreur.
661 */
662function noizetier_conteneur_construire($plugin, $id_conteneur) {
663
664        // Il faut recomposer le tableau du conteneur à partir de son id.
665        // N-Core s'occupe des noisettes conteneur; le noiZetier n'a donc plus qu'à traiter les autres conteneur,
666        // à savoir ses conteneurs spécifiques.
667        $conteneur = array();
668        if ($id_conteneur) {
669                $elements = explode('|', $id_conteneur);
670                if (count($elements) == 1) {
671                        // C'est une page ou une composition : seul l'index squelette est positionné.
672                        $conteneur['squelette'] = $id_conteneur;
673                } elseif (count($elements) == 3) {
674                        // C'est un objet
675                        // -- le type d'objet et son id
676                        $conteneur['objet'] = $elements[1];
677                        $conteneur['id_objet'] = $elements[2];
678                        // -- le squelette
679                        $conteneur['squelette'] = $elements[0];
680                }
681        }
682
683        return $conteneur;
684}
685
686
687/**
688 * Retire, de l'espace de stockage, toutes les noisettes d'un conteneur.
689 * L'imbrication des conteneurs est gérée dans la fonction de service de N-Core.
690 *
691 * @package SPIP\NOIZETIER\CONTENEUR\SERVICE
692 *
693 * @param string       $plugin
694 *        Identifiant qui permet de distinguer le module appelant qui peut-être un plugin comme le noiZetier ou
695 *        un script. Pour un plugin, le plus pertinent est d'utiliser le préfixe.
696 * @param array|string $conteneur
697 *        Tableau descriptif du conteneur ou identifiant du conteneur.
698 *
699 * @return bool
700 *        `true` si le traitement s'est bien déroulé, `false` sinon.
701 */
702function noizetier_conteneur_destocker($plugin, $conteneur) {
703
704        // Initialisation de la sortie.
705        $retour = false;
706
707        // Calcul de l'id du conteneur en fonction du mode d'appel de la fonction.
708        if (is_array($conteneur)) {
709                include_spip('inc/ncore_conteneur');
710                $id_conteneur = conteneur_identifier($plugin, $conteneur);
711        } else {
712                $id_conteneur = $conteneur;
713        }
714
715        if ($id_conteneur) {
716                // Suppression de toutes les noisettes du conteneur.
717                $where = array('id_conteneur=' . sql_quote($id_conteneur), 'plugin=' . sql_quote($plugin));
718                if (sql_delete('spip_noisettes', $where)) {
719                        $retour = true;
720                }
721        }
722
723        return $retour;
724}
Note: See TracBrowser for help on using the repository browser.