Browse Source

Conteneur et PHPDoc

svn/root/tags/v0.10.0
eric@smellup.net 5 years ago
parent
commit
d57506ab01
  1. 38
      inc/ncore_noisette.php
  2. 88
      ncore/ncore.php

38
inc/ncore_noisette.php

@ -1,7 +1,7 @@
<?php
/**
* Ce fichier contient l'API N-Core de gestion des noisettes, c'est-à-dire les instances paramétrées
* de types de noisette affectées à un squelette.
* de types de noisette affectées à un conteneur.
*
* @package SPIP\NCORE\API\NOISETTE
*/
@ -11,7 +11,7 @@ if (!defined('_ECRIRE_INC_VERSION')) {
/**
* Ajoute à un squelette contextualisé, à un rang donné ou en dernier rang, une noisette d'un type donné.
* Ajoute à un conteneur, à un rang donné ou en dernier rang, une noisette d'un type donné.
* La fonction met à jour les rangs des autres noisettes si nécessaire.
*
* @api
@ -76,7 +76,7 @@ function noisette_ajouter($plugin, $type_noisette, $conteneur, $rang = 0, $stock
// Ce sont ces fonctions qui aiguillent ou pas vers un service spécifique du plugin.
include_spip('ncore/ncore');
// On récupère les noisettes déjà affectées au squelette contextualisé sous la forme d'un tableau indexé
// On récupère les noisettes déjà affectées au conteneur sous la forme d'un tableau indexé
// par le rang de chaque noisette.
$noisettes = ncore_noisette_lister($plugin, $conteneur, '', 'rang', $stockage);
@ -112,7 +112,7 @@ function noisette_ajouter($plugin, $type_noisette, $conteneur, $rang = 0, $stock
}
/**
* Supprime une noisette donnée du squelette contextualisé auquel elle est associée.
* Supprime une noisette donnée du conteneur auquel elle est associée.
* La fonction met à jour les rangs des autres noisettes si nécessaire.
*
* @api
@ -146,11 +146,11 @@ function noisette_supprimer($plugin, $noisette, $stockage = '') {
// L'identifiant d'une noisette peut être fourni de deux façons :
// - par une valeur unique, celle créée lors de l'ajout et qui peut-être un entier (id d'une table SPIP) ou
// une chaine unique par exemple générée par uniqid().
// - ou par un tableau à trois entrées fournissant le squelette, le contexte d'utilisation et le rang
// (qui est unique pour un squelette contextualisé donné).
// - ou par un tableau à deux entrées fournissant le conteneur et le rang dans le conteneur
// (qui est unique pour un conteneur donné).
if (!empty($noisette) and (is_string($noisette) or is_numeric($noisette) or is_array($noisette))) {
// Avant de supprimer la noisette on sauvegarde sa description.
// Cela permet de conserver le rang, le squelette et le contexte indépendamment de l'identifiant
// Cela permet de conserver le rang et le conteneur indépendamment de l'identifiant
// utilisé pour spécifier la noisette.
$description = ncore_noisette_decrire($plugin, $noisette, $stockage);
@ -158,7 +158,7 @@ function noisette_supprimer($plugin, $noisette, $stockage = '') {
// destockage de choisir la méthode d'identification la plus adaptée.
$retour = ncore_noisette_destocker($plugin, $description, $stockage);
// On récupère les noisettes restant affectées au squelette contextualisé sous la forme d'un tableau indexé par rang.
// On récupère les noisettes restant affectées au conteneur sous la forme d'un tableau indexé par rang.
$autres_noisettes = ncore_noisette_lister(
$plugin,
unserialize($description['conteneur']),
@ -184,7 +184,7 @@ function noisette_supprimer($plugin, $noisette, $stockage = '') {
/**
* Retourne, pour une noisette donnée, la description complète ou seulement un champ précis.
* Les champs textuels peuvent subir une traitement typo si demandé.
* Les champs textuels peuvent subir un traitement typo si demandé.
*
* @api
* @uses ncore_squelette_identifier()
@ -213,7 +213,8 @@ function noisette_supprimer($plugin, $noisette, $stockage = '') {
function noisette_lire($plugin, $noisette, $information = '', $traiter_typo = false, $stockage = '') {
// On indexe le tableau des descriptions par le plugin appelant en cas d'appel sur le même hit
// par deux plugins différents. On gère un tableau par type d'identification (id noisette ou couple squelette/rang).
// par deux plugins différents.
// En outre, on gère un tableau par type d'identification, id noisette ou couple (conteneur, rang).
static $description_noisette_par_id = array();
static $description_noisette_par_rang = array();
@ -252,7 +253,8 @@ function noisette_lire($plugin, $noisette, $information = '', $traiter_typo = fa
}
}
// Sauvegarde de la description de la page pour une consultation ultérieure dans le même hit.
// Sauvegarde de la description de la noisette pour une consultation ultérieure dans le même hit
// en suivant le type d'identification.
if (is_array($noisette)) {
$description_noisette_par_rang[$plugin][$id_conteneur][$noisette['rang']] = $description;
} else {
@ -281,7 +283,7 @@ function noisette_lire($plugin, $noisette, $information = '', $traiter_typo = fa
}
/**
* Déplace une noisette donnée au sein d’un squelette contextualisé.
* Déplace une noisette donnée au sein d’un conteneur.
* La fonction met à jour les rangs des autres noisettes si nécessaire.
*
* @api
@ -316,8 +318,8 @@ function noisette_deplacer($plugin, $noisette, $rang_destination, $stockage = ''
// L'identifiant d'une noisette peut être fourni de deux façons :
// - par une valeur unique, celle créée lors de l'ajout et qui peut-être un entier (id d'une table SPIP) ou
// une chaine unique par exemple générée par uniqid().
// - ou par un tableau à trois entrées fournissant le squelette, le contexte et le rang
// (qui est unique pour un squelette donné).
// - ou par un tableau à deux entrées fournissant le conteneur et le rang
// (qui est unique pour un conteneur donné).
if (!empty($noisette) and (is_string($noisette) or is_numeric($noisette) or is_array($noisette))) {
// Avant de deplacer la noisette on sauvegarde sa description et son rang origine.
$description = ncore_noisette_decrire($plugin, $noisette, $stockage);
@ -325,7 +327,7 @@ function noisette_deplacer($plugin, $noisette, $rang_destination, $stockage = ''
// Si les rangs origine et destination sont identiques on ne fait rien !
if ($rang_destination != $rang_origine) {
// On récupère les noisettes affectées au même squelette sous la forme d'un tableau indexé par le rang.
// On récupère les noisettes affectées au même conteneur sous la forme d'un tableau indexé par le rang.
$noisettes = ncore_noisette_lister(
$plugin,
unserialize($description['conteneur']),
@ -334,14 +336,14 @@ function noisette_deplacer($plugin, $noisette, $rang_destination, $stockage = ''
$stockage
);
// On vérifie que le rang destination soit bien compris entre 1 et le rang max, sinon on le force à une
// On vérifie que le rang destination est bien compris entre 1 et le rang max, sinon on le force à l'une
// des bornes.
$rang_destination = max(1, $rang_destination);
$rang_max = $noisettes ? max(array_keys($noisettes)) : 0;
$rang_destination = min($rang_max, $rang_destination);
// Suivant la position d'origine et de destination de la noisette déplacée on trie les noisettes
// du squelette contextualisé.
// du conteneur.
if ($rang_destination < $rang_origine) {
krsort($noisettes);
} else {
@ -377,7 +379,7 @@ function noisette_deplacer($plugin, $noisette, $rang_destination, $stockage = ''
/**
* Supprime toutes les noisettes d’un squelette contextualisé.
* Supprime toutes les noisettes d’un conteneur.
*
* @api
* @uses ncore_noisette_destocker()

88
ncore/ncore.php

@ -222,7 +222,7 @@ function ncore_type_noisette_lister($plugin, $information = '', $stockage = '')
// -----------------------------------------------------------------------
/**
* Stocke la description d'une nouvelle noisette et calcule son identifiant unique ou met à jour les paramètres
* Stocke la description d'une nouvelle noisette et calcule son identifiant unique, ou met à jour les paramètres
* d'affichage d'une noisette existante.
*
* @package SPIP\NCORE\SERVICE\NOISETTE
@ -240,7 +240,7 @@ function ncore_type_noisette_lister($plugin, $information = '', $stockage = '')
* Identifiant du service de stockage à utiliser si précisé. Dans ce cas, ni celui du plugin ni celui de N-Core
* ne seront utilisés. En général, cet identifiant est le préfixe du plugin fournissant le stockage.
*
* @return mixed
* @return int|string
* Id de la noisette de type entier ou chaine.
* Le stockage N-Core renvoie lui une chaine construite à partir du plugin et de la fonction uniqid().
*/
@ -257,16 +257,16 @@ function ncore_noisette_stocker($plugin, $description, $stockage = '') {
} else {
// Le plugin ne propose pas de fonction propre ou le stockage N-Core est explicitement demandé.
// -- N-Core stocke les noisettes dans une meta propre au plugin appelant contenant un tableau au format
// [squelette contextualisé][rang] = description
// N-Core calcule un identifiant unique pour la noisette qui sera stocké à l'index 'id_noisette' et qui
// vaudra uniqid() avec comme préfixe le plugin appelant.
// [conteneur][rang] = description
// N-Core calcule un identifiant unique pour la noisette qui sera stocké à l'index 'id_noisette' de sa
// description et qui vaudra uniqid() avec comme préfixe le plugin appelant.
// On lit la meta de stockage des noisettes pour le plugin appelant.
include_spip('inc/config');
$noisettes = lire_config("${plugin}_noisettes", array());
// Détermination de l'identifiant du squelette contextualisé. Le squelette et le contexte font partie de
// la description, le contexte est lui sérialisé.
// Détermination de l'identifiant du conteneur. Le conteneur est un tableau sérialisé qui fait partie
// de la description.
$id_conteneur = ncore_conteneur_identifier(
$plugin,
unserialize($description['conteneur']),
@ -276,14 +276,13 @@ function ncore_noisette_stocker($plugin, $description, $stockage = '') {
if (empty($description['id_noisette'])) {
// Ajout de la noisette :
// -- la description est complète à l'exception de l'id unique qui est créé à la volée
// -- et on range la noisette avec les noisettes affectées au même squelette contextualisé
// en fonction de son rang.
// -- et on range la noisette avec les noisettes affectées au même conteneur en fonction de son rang.
$description['id_noisette'] = uniqid("${plugin}_");
$noisettes[$id_conteneur][$description['rang']] = $description;
} else {
// Modification de la noisette :
// -- les informations identifiant sont toujours fournies, à savoir, l'id, le squelette, le contexte et le rang.
// -- on utilise le squelette contextualisé et le rang pour se positionner sur la noisette concernée.
// -- les identifiants de la noisette sont toujours fournies, à savoir, l'id, le conteneur et le rang.
// -- on utilise le conteneur et le rang pour se positionner sur la noisette concernée.
// -- Les modifications ne concernent que les paramètres d'affichage, cette fonction n'est jamais utilisée
// pour le changement de rang.
if (isset($noisettes[$id_conteneur][$description['rang']])) {
@ -306,7 +305,7 @@ function ncore_noisette_stocker($plugin, $description, $stockage = '') {
/**
* Positionne une noisette à un rang différent que celui qu'elle occupe dans le squelette contextualisé.
* Positionne une noisette à un rang différent que celui qu'elle occupe dans le conteneur.
*
* @package SPIP\NCORE\SERVICE\NOISETTE
*
@ -319,7 +318,7 @@ function ncore_noisette_stocker($plugin, $description, $stockage = '') {
* @param array $description
* Description complète de la noisette.
* @param int $rang_destination
* Position à laquelle ranger la noisette au sein du squelette contextualisé.
* Position à laquelle ranger la noisette au sein du conteneur.
* @param string $stockage
* Identifiant du service de stockage à utiliser si précisé. Dans ce cas, ni celui du plugin ni celui de N-Core
* ne seront utilisés. En général, cet identifiant est le préfixe du plugin fournissant le stockage.
@ -343,23 +342,23 @@ function ncore_noisette_ranger($plugin, $description, $rang_destination, $stocka
} else {
// Le plugin ne propose pas de fonction propre ou le stockage N-Core est explicitement demandé.
// -- N-Core stocke les noisettes dans une meta propre au plugin appelant contenant un tableau au format
// [squelette contextualisé][rang] = description
// [conteneur][rang] = description
// On lit la meta de stockage des noisettes pour le plugin appelant.
include_spip('inc/config');
$noisettes = lire_config("${plugin}_noisettes", array());
// Détermination de l'identifiant du squelette contextualisé. Le squelette et le contexte font partie de
// la description, le contexte est lui sérialisé.
// Détermination de l'identifiant du conteneur. Le conteneur est un tableau sérialisé qui fait partie
// de la description.
$id_conteneur = ncore_conteneur_identifier(
$plugin,
unserialize($description['conteneur']),
$stockage
);
// On ajoute la noisette au rang choisi même si on doit écraser un index existant.
// Il est donc nécessaire de gérer la collision en amont de cette fonction.
// Par contre, l'ancien rang de la noisette est supprimé sauf si celui-ci est à zéro.
// On ajoute la noisette au rang choisi même si on doit écraser un index existant:
// -- Il est donc nécessaire de gérer la collision en amont de cette fonction.
// -- Par contre, l'ancien rang de la noisette est supprimé sauf si celui-ci est à zéro.
$rang_source = $description['rang'];
$description['rang'] = $rang_destination;
$noisettes[$id_conteneur][$rang_destination] = $description;
@ -376,8 +375,7 @@ function ncore_noisette_ranger($plugin, $description, $rang_destination, $stocka
}
/**
* Retire une noisette donnée de son squelette contextualisé ou retire l'ensemble des noisettes
* d'un squelette contextualisé de l'espace de stockage.
* Retire, de l'espace de stockage, une noisette donnée de son conteneur ou l'ensemble des noisettes d'un conteneur.
*
* @package SPIP\NCORE\SERVICE\NOISETTE
*
@ -388,7 +386,7 @@ function ncore_noisette_ranger($plugin, $description, $rang_destination, $stocka
* 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 $description
* Description complète de la noisette ou identifiant du squelette contextualisé.
* Description complète de la noisette ou identifiant du conteneur.
* @param string $stockage
* Identifiant du service de stockage à utiliser si précisé. Dans ce cas, ni celui du plugin ni celui de N-Core
* ne seront utilisés. En général, cet identifiant est le préfixe du plugin fournissant le stockage.
@ -412,14 +410,14 @@ function ncore_noisette_destocker($plugin, $description, $stockage = '') {
} else {
// Le plugin ne propose pas de fonction propre ou le stockage N-Core est explicitement demandé.
// -- N-Core stocke les noisettes dans une meta propre au plugin appelant contenant un tableau au format
// [squelette contextualisé][rang] = description
// -- $description est soit le tableau descriptif de la noisette, soit le tableau formé uniquement du couple
// (squelette, contexte) et dans ce cas, il faut supprimer toutes les noisettes du squelette contextualisé.
// [conteneur][rang] = description
// -- $description est soit le tableau descriptif de la noisette, soit le conteneur, et dans ce cas, il faut
// supprimer toutes les noisettes du conteneur.
include_spip('inc/config');
$meta_noisettes = lire_config("${plugin}_noisettes", array());
// Détermination de l'identifiant du squelette contextualisé. Le squelette et le contexte font partie de
// la description, le contexte est lui sérialisé.
// Détermination de l'identifiant du conteneur. Le conteneur est un tableau sérialisé qui fait partie
// de la description.
$id_conteneur = ncore_conteneur_identifier(
$plugin,
unserialize($description['conteneur']),
@ -429,13 +427,14 @@ function ncore_noisette_destocker($plugin, $description, $stockage = '') {
if (!empty($description['id_noisette']) and isset($meta_noisettes[$id_conteneur][$description['rang']])) {
// On supprime une noisette donnée.
unset($meta_noisettes[$id_conteneur][$description['rang']]);
// Si c'était la dernière noisette il faut aussi supprimer l'index correspondant au squelette contextualisé.
// Si c'est la dernière noisette du conteneur il faut aussi supprimer l'index correspondant au conteneur.
if (!$meta_noisettes[$id_conteneur]) {
unset($meta_noisettes[$id_conteneur]);
}
ecrire_config("${plugin}_noisettes", $meta_noisettes);
$retour = true;
} elseif (isset($meta_noisettes[$id_conteneur])) {
// On supprime toutes les noisettes du conteneur.
unset($meta_noisettes[$id_conteneur]);
ecrire_config("${plugin}_noisettes", $meta_noisettes);
$retour = true;
@ -447,9 +446,8 @@ function ncore_noisette_destocker($plugin, $description, $stockage = '') {
/**
* Renvoie une donnée ou toute la description des noisettes d'un squelette contextualisé ou de tous les squelettes
* contextualisés.
* Le tableau retourné est indexé soit par identifiant de noisette soit par squelette contextualisé et rang.
* Renvoie un champ ou toute la description des noisettes d'un conteneur ou de tous les conteneurs.
* Le tableau retourné est indexé soit par identifiant de noisette soit par conteneur et rang.
*
* @package SPIP\NCORE\SERVICE\NOISETTE
*
@ -494,12 +492,12 @@ function ncore_noisette_lister($plugin, $conteneur = array(), $information = '',
} else {
// Le plugin ne propose pas de fonction propre ou le stockage N-Core est explicitement demandé.
// -- N-Core stocke les noisettes dans une meta propre au plugin appelant contenant un tableau au format
// [squelette contextualisé][rang] = description
// [conteneur][rang] = description
include_spip('inc/config');
$meta_noisettes = lire_config("${plugin}_noisettes", array());
if ($conteneur) {
// Détermination de l'identifiant du squelette contextualisé.
// Détermination de l'identifiant du conteneur.
$id_conteneur = ncore_conteneur_identifier($plugin, $conteneur, $stockage);
if (!empty($meta_noisettes[$id_conteneur])) {
$noisettes = $meta_noisettes[$id_conteneur];
@ -526,8 +524,8 @@ function ncore_noisette_lister($plugin, $conteneur = array(), $information = '',
/**
* Renvoie la description brute d'une noisette sans traitement typo ni désérialisation des champs de type
* tableau sérialisé.
* Renvoie la description brute d'une noisette sans traitement typo des champs textuels ni désérialisation
* des champs de type tableau sérialisé.
*
* @package SPIP\NCORE\SERVICE\NOISETTE
*
@ -563,7 +561,7 @@ function ncore_noisette_decrire($plugin, $noisette, $stockage = '') {
} else {
// Le plugin ne propose pas de fonction propre ou le stockage N-Core est explicitement demandé.
// -- N-Core stocke les noisettes dans une meta propre au plugin appelant contenant un tableau au format
// [squelette contextualisé][rang] = description
// [conteneur][rang] = description
include_spip('inc/config');
$meta_noisettes = lire_config("${plugin}_noisettes", array());
@ -588,14 +586,14 @@ function ncore_noisette_decrire($plugin, $noisette, $stockage = '') {
}
} else {
if (isset($noisette['squelette'], $noisette['contexte'], $noisette['rang'])) {
// Détermination de l'identifiant du squelette contextualisé.
// Détermination de l'identifiant du conteneur.
$id_conteneur = ncore_conteneur_identifier(
$plugin,
$noisette['conteneur'],
$stockage
);
if (!empty($meta_noisettes[$id_conteneur][$noisette['rang']])) {
// L'identifiant est un tableau associatif fournissant le squelette contextualisé et le rang.
// L'identifiant est un tableau associatif fournissant le conteneur et le rang.
// Comme la meta de N-Core est structurée ainsi c'est la méthode la plus adaptée pour adresser
// le stockage de N-Core.
$description = $meta_noisettes[$id_conteneur][$noisette['rang']];
@ -609,7 +607,7 @@ function ncore_noisette_decrire($plugin, $noisette, $stockage = '') {
}
/**
* Construit un identifiant unique pour le squelette et son contexte sous forme de chaine.
* Construit un identifiant unique pour le conteneur sous forme de chaine.
* Cette fonction est juste un aiguillage vers la fonction éventuelle du plugin utilisateur
* car N-Core ne fournit pas de calcul par défaut.
*
@ -630,16 +628,14 @@ function ncore_noisette_decrire($plugin, $noisette, $stockage = '') {
* ne seront utilisés. En général, cet identifiant est le préfixe du plugin fournissant le stockage.
*
* @return string
* Identifiant du squelette contextualisé.
* Identifiant du conteneur ou chaine vide en cas d'erreur.
*/
function ncore_conteneur_identifier($plugin, $conteneur, $stockage) {
// Il faut calculer l'identifiant du squelette contextualisé pour accéder à la bonne liste
// de noisettes. N-Core ne propose pas de fonction par défaut car l'élaboration de l'identifiant
// en fonction du contexte est totalement spécifique au plugin utilisateur.
// Il est donc indispensable que le plugin qui nécessite l'utilisation d'un contexte propose la
// fonction de calcul associée sinon le contexte ne sera pas pris en compte et seul l'identifiant
// du squelette sera retourné.
// Il faut calculer l'identifiant du conteneur pour accéder à la bonne liste de noisettes.
// N-Core ne propose pas de fonction par défaut car l'élaboration de l'identifiant est totalement spécifique
// au plugin utilisateur.
// Il est donc indispensable que le plugin utilisateur propose toujours une fonction de calcul de l'identifiant.
$id_conteneur = '';
if ($conteneur) {
include_spip('inc/ncore_utils');

Loading…
Cancel
Save