spip-contrib-extensions
/
n-core
126
2
Fork 0
Code Issues 1 Pull Requests Releases Wiki Activity

PHPdoc sur le service noisettes de N-Core

Browse Source
svn/attic/tags/v010/106508
eric@smellup.net 6 years ago
parent 37c5d8ad3a
commit 122c988a01
2 changed files with 95 additions and 21 deletions
Show Stats Download Patch File Download Diff File

95
ncore/ncore.php
Unescape Escape View File

@ -1,5 +1,14 @@
<?php
/**
* Ce fichier contient les fonctions du service N-Core pour les noisettes.
*
* Chaque fonction, soit aiguille vers une fonction "homonyme" propre au service si elle existe,
* soit déroule sa propre implémentation pour le service appelant.
* Ainsi, les services externes peuvent, si elle leur convient, utiliser l'implémentation proposée par N-Core
* sans coder la moindre fonction.
*
* @package SPIP\NCORE\NOISETTE\SERVICE
*/
if (!defined('_ECRIRE_INC_VERSION')) {
return;
}
@ -15,16 +24,26 @@ if (!defined('_NCORE_CONFIG_AJAX_DEFAUT')) {
if (!defined('_NCORE_DYNAMIQUE_DEFAUT')) {
/**
* Valeur par défaut de l'indicateur d'inclusion dynamique des noisettes.
* Pour N-Core, le défaut est `false`
* Pour N-Core, le défaut est `false`.
*/
define('_NCORE_DYNAMIQUE_DEFAUT', false);
}
/**
* @param $service
* Retourne la liste des signatures des fichiers YAML des noisettes détectées par le service.
*
* Le service N-Core lit les signatures dans un cache dédié.
*
* @uses cache_lire()
*
* @param string $service
* Le service permet de distinguer l'appelant qui peut-être un plugin comme le noiZetier ou
* un script. Pour un plugin, le plus pertinent est d'utiliser le préfixe.
* Cet argument n'est utilisé que si la fonction N-Core est appelée.
*
* @return array
* Tableau des signatures de noisettes au format `[noisette] = signature`.
*/
function ncore_noisette_lister_signatures($service) {
@ -44,11 +63,32 @@ function ncore_noisette_lister_signatures($service) {
}
/**
* @param $service
* @param $noisettes
* @param $recharger
* Stocke les descriptions de noisettes en distinguant les noisettes obsolètes, les noisettes modifiées et
* les noisettes nouvelles.
* Chaque description de noisette est un tableau associatif dont tous les index possibles - y compris la signature -
* sont initialisés quelque soit le contenu du fichier YAML.
*
* Le service N-Core stocke les descriptions dans un cache dédié et les signatures dans un autre.
*
* @uses cache_lire()
* @uses cache_ecrire()
*
* @param string $service
* Le service permet de distinguer l'appelant qui peut-être un plugin comme le noiZetier ou
* un script. Pour un plugin, le plus pertinent est d'utiliser le préfixe.
* Cet argument n'est utilisé que si la fonction N-Core est appelée.
* @param array $noisettes
* Tableau associatif à 3 entrées fournissant les descriptions des noisettes nouvelles, obsolètes et modifiées:
* - `obsoletes` : liste des identifiants de noisette devenus obsolètes;
* - `modifiees` : liste des descriptions des noisettes dont le fichier YAML a été modifié;
* - `nouvelles` : liste des descriptions de nouvelles noisettes. Cet index est le seul fourni si l'indicateur
* $recharger est à `true`.
* @param bool $recharger
* Indique si le chargement en cours est forcé ou pas. Cela permet à la fonction N-Core ou du service
* concerné d'optimiser le traitement sachant que seules les noisettes nouvelles sont fournies.
*
* @return bool
* `true` si le traitement s'est bien déroulé, `false` sinon.
*/
function ncore_noisette_stocker($service, $noisettes, $recharger) {
@ -110,10 +150,22 @@ function ncore_noisette_stocker($service, $noisettes, $recharger) {
}
/**
* @param $service
* @param $noisette
* Renvoie la description brute d'une noisette sans traitement typo ni désérialisation des champs.
*
* Le service N-Core lit la description de la noisette concernée dans le cache des descriptions.
*
* @uses cache_lire()
*
* @param string $service
* Le service permet de distinguer l'appelant qui peut-être un plugin comme le noiZetier ou
* un script. Pour un plugin, le plus pertinent est d'utiliser le préfixe.
* Cet argument n'est utilisé que si la fonction N-Core est appelée.
* @param string $noisette
* Identifiant de la noisette.
*
* @return array
* Tableau de la description de la noisette. Les champs textuels et les champs de type tableau sérialisé
* sont retournés en l'état.
*/
function ncore_noisette_decrire($service, $noisette) {
@ -139,9 +191,19 @@ function ncore_noisette_decrire($service, $noisette) {
}
/**
* @param $service
* Renvoie la configuration par défaut de l'ajax à appliquer pour les noisettes.
* Cette information est utilisée si la description YAML d'une noisette ne contient pas de tag ajax
* ou contient un tag ajax à `defaut`.
*
* Le service N-Core considère que toute noisette est par défaut insérée en ajax.
*
* @param string $service
* Le service permet de distinguer l'appelant qui peut-être un plugin comme le noiZetier ou
* un script. Pour un plugin, le plus pertinent est d'utiliser le préfixe.
* Cet argument n'est utilisé que si la fonction N-Core est appelée.
*
* @return bool
* `true` si par défaut une noisette est insérée en ajax, `false` sinon.
*/
function ncore_noisette_config_ajax($service) {
@ -159,10 +221,20 @@ function ncore_noisette_config_ajax($service) {
}
/**
* @param $service
* @param $information
* Renvoie l'information brute demandée pour l'ensemble des noisettes utilisées par le service.
*
* @uses cache_lire()
*
* @param string $service
* Le service permet de distinguer l'appelant qui peut-être un plugin comme le noiZetier ou
* un script. Pour un plugin, le plus pertinent est d'utiliser le préfixe.
* Cet argument n'est utilisé que si la fonction N-Core est appelée.
* @param string $information
* Identifiant d'un champ de la description d'une noisette. Si l'argument est vide ou invalide,
* la fonction renvoie un tableau vide.
*
* @return array
* Tableau de la forme `[noisette] = information`.
*/
function ncore_noisette_lister($service, $information) {
@ -179,6 +251,7 @@ function ncore_noisette_lister($service, $information) {
if ($information) {
include_spip('inc/ncore_cache');
if ($descriptions = cache_lire($service, _NCORE_NOMCACHE_NOISETTE_DESCRIPTION)) {
// Si $information n'est pas une colonne valide la fonction retournera un tableau vide.
$information_noisettes = array_column($descriptions, $information, 'noisette');
}
}

21
ncore_fonctions.php
Unescape Escape View File

@ -1,6 +1,9 @@
<?php
// Securite
/**
* Ce fichier contient l'API N-Core de gestion des noisettes.
*
* @package SPIP\NCORE\NOISETTE\API
*/
if (!defined('_ECRIRE_INC_VERSION')) {
return;
}
@ -10,13 +13,12 @@ if (!defined('_ECRIRE_INC_VERSION')) {
// -------------------------------------------------------------------
/**
* Chargement ou rechargement de descriptions de noisettes à partir de leurs fichiers YAML.
* Charge ou recharge les descriptions de noisettes à partir des fichiers YAML.
* Les noisettes sont recherchées dans un répertoire relatif fourni en argument.
* La fonction optimise le chargement en effectuant uniquement les traitements nécessaires
* en fonction des modifications, ajouts et suppressions de noisettes identifiés en comparant les md5
* des fichiers YAML.
*
* @package SPIP\NCORE\NOISETTE
* @api
* @filtre
*
@ -145,7 +147,6 @@ function ncore_noisette_charger($service, $dossier = 'noisettes/', $recharger =
* Retourne la description complète ou seulement une information précise pour une noisette donnée.
* Les données textuelles peuvent subir une traitement typo si demandé.
*
* @package SPIP\NCORE\NOISETTE
* @api
* @filtre
*
@ -164,6 +165,9 @@ function ncore_noisette_charger($service, $dossier = 'noisettes/', $recharger =
* Les champs sérialisés sont eux toujours désérialisés.
*
* @return array|string
* La description complète ou l'information précise demandée pour une noisette donnée. Les champs
* de type tableau sont systématiquement désérialisés et si demandé, les champs textuels peuvent être
* traités avec la fonction _T_ou_typo().
*/
function ncore_noisette_informer($service, $noisette, $information = '', $traiter_typo = false) {
@ -174,7 +178,7 @@ function ncore_noisette_informer($service, $noisette, $information = '', $traite
// Stocker la description de la noisette si besoin
if (!isset($description_noisette[$service][$noisette])) {
// On charge l'API de NCore.
// On charge l'API de N-Core.
// Ce sont ces fonctions qui aiguillent ou pas vers une fonction spécifique du service.
include_spip("ncore/ncore");
@ -224,7 +228,6 @@ function ncore_noisette_informer($service, $noisette, $information = '', $traite
/**
* Détermine si la noisette spécifiée doit être incluse en AJAX ou pas.
*
* @package SPIP\NCORE\NOISETTE
* @api
* @filtre
*
@ -254,7 +257,7 @@ function ncore_noisette_est_ajax($service, $noisette) {
if (!$est_ajax[$service]
or (_request('var_mode') == 'recalcul')
or (defined('_NO_CACHE') and (_NO_CACHE != 0))) {
// On charge l'API de NCore.
// On charge l'API de N-Core.
// Ce sont ces fonctions qui aiguillent ou pas vers une fonction spécifique du service.
include_spip("ncore/ncore");
@ -290,7 +293,6 @@ function ncore_noisette_est_ajax($service, $noisette) {
/**
* Détermine si la noisette spécifiée doit être incluse dynamiquement ou pas.
*
* @package SPIP\NCORE\NOISETTE
* @api
* @filtre
*
@ -350,7 +352,6 @@ function ncore_noisette_est_dynamique($service, $noisette) {
/**
* Renvoie le contexte de la noisette sous la forme d'un tableau éventuellement vide.
*
* @package SPIP\NCORE\NOISETTE
* @api
* @filtre
*

Write Preview
Loading…
Cancel
Save