Documentation du code de SPIP et de ses plugins

REST Factory

Documentation

Packages

Application
SPIP

Table of Contents

ezrest_cache_configurer()  : array<string|int, mixed>
Renvoie la configuration spécifique des caches gérés par REST Factory si les fonctions de collection des données sont directement codés en PHP.
ezrest_reponse_cache_formulaire_charger()  : array<string|int, mixed>
Effectue le chargement du formulaire de vidage des caches de type `reponse` pour le plugin REST Factory.
ezrest_index_cache_formulaire_charger()  : array<string|int, mixed>
Effectue le chargement du formulaire de vidage des caches de type `index` pour le plugin REST Factory.
ezrest_api_verifier_contexte()  : bool
Détermine si le serveur est capable de répondre aux requêtes.
ezrest_reponse_initialiser_contenu()  : array<string|int, mixed>
Initialise le contenu d'une réponse qui se présente comme un tableau associatif.
ezrest_reponse_informer_plugin()  : array<string|int, mixed>
Complète l'initialisation du contenu d'une réponse avec des informations sur le plugin utilisateur.
ezrest_reponse_expliquer_erreur()  : array<string|int, mixed>
Complète le bloc d'erreur avec le titre et l'explication de l'erreur.
ezrest_reponse_construire()  : Response
Finalise la réponse à la requête en complétant le header et le contenu mis au préalable au format JSON.
ezrest_collection_verifier()  : bool
Détermine si la collection demandée est valide. Par défaut, REST Factory vérifie que la collection est bien déclarée dans la liste des collections. Si c'est le cas, la fonction permet ensuite au plugin utilisateur de compléter la vérification, si besoin.
ezrest_collection_verifier_filtre()  : bool
Détermine si la valeur de chaque critère de filtre d'une collection est valide.
ezrest_collection_verifier_ressource()  : bool
Détermine si le type de ressource demandée est valide.
ezrest_indexer()  : array<string|int, mixed>
Construit l'index des collections disponibles avec leur configuration expliquée.
ezrest_contextualiser()  : array<string|int, mixed>
Construit le contexte à fournir au fichier HTML qui produira le JSON des données de la réponse.
ezrest_cache_identifier()  : array<string|int, mixed>
Construit l'identifiant relatif du fichier cache (plugin Cache Factory) dans lequel sera stockée la réponse à la requête.
ezrest_conditionner()  : array<string|int, mixed>
Construit le tableau des conditions SQL à appliquer à la collection.
ezrest_collectionner()  : array<string|int, mixed>
Renvoie les données correspondant à la collection et aux filtres demandés.
ezrest_ressourcer()  : array<string|int, mixed>
Renvoie les données correspondant à la ressource demandée.
ezrest_post_cache()  : mixed
Ajoute ou retire le cache créé ou supprimé de l'index des caches REST Factory.
http_ezrest_erreur_dist()  : Response
Traite les erreurs directement détectées par le serveur HTTP abstrait uniquement.
http_ezrest_get_index_dist()  : Response
Fait un GET sur l'API ezREST seule et renvoie la liste des collections disponibles et les possibilités associées.
http_ezrest_get_collection_dist()  : Response
Fait un GET sur une collection gérée par l'API ezREST.
http_ezrest_get_ressource_dist()  : Response
Fait un GET sur une ressource d'une collection gérée par l'API ezREST.
inc_ezrest_declarer_collections_dist()  : array<string|int, mixed>
Déclare les collections accessibles via HTTP GET.

Functions

ezrest_cache_configurer()

Renvoie la configuration spécifique des caches gérés par REST Factory si les fonctions de collection des données sont directement codés en PHP.

ezrest_cache_configurer(string $plugin) : array<string|int, mixed>

Dans le cas où les données JSON sont créées via des squelettes SPIP, le cache est déjà géré par SPIP.

Parameters
$plugin : string

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.

Return values
array<string|int, mixed>

Tableau de la configuration brute du plugin Taxonomie.

ezrest_reponse_cache_formulaire_charger()

Effectue le chargement du formulaire de vidage des caches de type `reponse` pour le plugin REST Factory.

ezrest_reponse_cache_formulaire_charger(string $plugin, array<string|int, mixed> $valeurs, array<string|int, mixed> $options, array<string|int, mixed> $configuration) : array<string|int, mixed>

L'intérêt est de permette le rangement des caches par type de requête.

Parameters
$plugin : string

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.

$valeurs : array<string|int, mixed>

Tableau des valeurs du formulaire à compléter

$options : array<string|int, mixed>

Tableau d'options qui peut être fourni par un plugin utilisateur uniquement si celui-ci fait appel au formulaire. La page cache_vider de Cache Factory n'utilise pas ce paramètre. Le tableau est passé à la fonction de service de chargement du formulaire uniquement.

$configuration : array<string|int, mixed>

Configuration complète des caches du plugin utilisateur lue à partir de la meta de stockage.

Tags
uses
cache_repertorier()
Return values
array<string|int, mixed>

Tableau des valeurs du formulaire complété par la structure propre au type de cache.

ezrest_index_cache_formulaire_charger()

Effectue le chargement du formulaire de vidage des caches de type `index` pour le plugin REST Factory.

ezrest_index_cache_formulaire_charger(string $plugin, array<string|int, mixed> $valeurs, array<string|int, mixed> $options, array<string|int, mixed> $configuration) : array<string|int, mixed>

L'index est unique et comme sa suppression peut être sensible, le formulaire affiche un avertissement.

Parameters
$plugin : string

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.

$valeurs : array<string|int, mixed>

Tableau des valeurs du formulaire à compléter

$options : array<string|int, mixed>

Tableau d'options qui peut être fourni par un plugin utilisateur uniquement si celui-ci fait appel au formulaire. La page cache_vider de Cache Factory n'utilise pas ce paramètre. Le tableau est passé à la fonction de service de chargement du formulaire uniquement.

$configuration : array<string|int, mixed>

Configuration complète des caches du plugin utilisateur lue à partir de la meta de stockage.

Tags
uses
cache_repertorier()
Return values
array<string|int, mixed>

Tableau des valeurs du formulaire complété par la structure propre au type de cache.

ezrest_api_verifier_contexte()

Détermine si le serveur est capable de répondre aux requêtes.

ezrest_api_verifier_contexte(string $plugin, array<string|int, mixed> &$erreur) : bool

Par défaut, l'API ezREST ne fait aucune vérification. C'est donc au plugin utilisateur de fournir un service spécifique si une vérification globale doit être effectuée afin d'assurer le fonctionnement de l'API.

Si une erreur est détectée, le plugin utilisateur ne renvoie le type, l'élément et la valeur qui provoque l'erreur sachant que c'est le service par défaut qui positionne le code.

Parameters
$plugin : string

Préfixe du plugin utilisateur de ezrest et donc fournisseur de la collection.

$erreur : array<string|int, mixed>

Tableau initialisé avec les index identifiant l'erreur ou vide si pas d'erreur.

Return values
bool

true si la valeur est valide, false sinon.

ezrest_reponse_initialiser_contenu()

Initialise le contenu d'une réponse qui se présente comme un tableau associatif.

ezrest_reponse_initialiser_contenu(Request $requete) : array<string|int, mixed>

En particulier, la fonction stocke les éléments de la requête et positionne le bloc d'erreur par défaut à ok.

Ce service standard n'est pas personnalisable par un plugin utilisateur.

Parameters
$requete : Request

Objet requête fourni par le plugin Serveur HTTP abstrait.

Return values
array<string|int, mixed>

Le contenu initial de la réponse est un tableau associatif à 3 entrées:

  • requete : sous-tableau des éléments de la requête
  • erreur : sous-tableau des éléments descriptifs d'une erreur (status 200 par défaut)
  • donnees : le tableau des objets demandés fonction de la requête (vide)

ezrest_reponse_informer_plugin()

Complète l'initialisation du contenu d'une réponse avec des informations sur le plugin utilisateur.

ezrest_reponse_informer_plugin(string $plugin, array<string|int, mixed> $contenu) : array<string|int, mixed>

REST Factory remplit de façon standard un nouvel index plugin du contenu et permet ensuite au plugin utilisateur de personnaliser encore le contenu initialisé, si besoin.

Parameters
$plugin : string

Préfixe du plugin utilisateur de ezrest et donc fournisseur de la collection.

$contenu : array<string|int, mixed>

Le contenu de la réponse initialisé par ezrest_reponse_initialiser_contenu.

Return values
array<string|int, mixed>

Le contenu initial de la réponse complétée par l'index fournisseur qui fournit des informations sur le plugin utilisateur.

ezrest_reponse_expliquer_erreur()

Complète le bloc d'erreur avec le titre et l'explication de l'erreur.

ezrest_reponse_expliquer_erreur(string $plugin, array<string|int, mixed> $erreur[, string $collection = '' ]) : array<string|int, mixed>
Parameters
$plugin : string

Préfixe du plugin utilisateur de ezrest et donc fournisseur de la collection.

$erreur : array<string|int, mixed>

Tableau initialisé avec les éléments de base de l'erreur (status, type, element et valeur).

$collection : string = ''

Identifiant de la collection

Return values
array<string|int, mixed>

Tableau de l'erreur complété avec le titre (index title) et le descriptif (index detail).

ezrest_reponse_construire()

Finalise la réponse à la requête en complétant le header et le contenu mis au préalable au format JSON.

ezrest_reponse_construire(Response $reponse, array<string|int, mixed> $contenu) : Response

Ce service standard n'est pas personnalisable par un plugin utilisateur.

Parameters
$reponse : Response

Objet réponse tel qu'initialisé par le serveur HTTP abstrait.

$contenu : array<string|int, mixed>

Tableau du contenu de la réponse qui sera retourné en JSON.

Return values
Response

Retourne l'objet réponse dont le contenu et certains attributs du header sont mis à jour.

ezrest_collection_verifier()

Détermine si la collection demandée est valide. Par défaut, REST Factory vérifie que la collection est bien déclarée dans la liste des collections. Si c'est le cas, la fonction permet ensuite au plugin utilisateur de compléter la vérification, si besoin.

ezrest_collection_verifier(string $collection, string &$plugin, array<string|int, mixed> &$erreur) : bool
Parameters
$collection : string

L'identifiant de la collection demandée

$plugin : string

Préfixe du plugin fournisseur de la collection. Chaine vide en entrée et en sortie si une erreur est détectée.

$erreur : array<string|int, mixed>

Tableau initialisé avec les index identifiant l'erreur ou vide si pas d'erreur. Les index mis à jour sont:

  • status : le code de l'erreur HTTP, soit 400
  • type : chaine identifiant l'erreur plus précisément, soit collection_nok
  • element : type d'objet sur lequel porte l'erreur, soit collection
  • valeur : la valeur de la collection
Return values
bool

true si la valeur est valide, false sinon.

ezrest_collection_verifier_filtre()

Détermine si la valeur de chaque critère de filtre d'une collection est valide.

ezrest_collection_verifier_filtre(string $plugin, array<string|int, mixed> $filtres, string $collection, array<string|int, mixed> $configuration, array<string|int, mixed> &$erreur) : bool

Si plusieurs critères sont fournis, la fonction s'interromp dès qu'elle trouve un critère non admis ou dont la valeur est invalide.

Parameters
$plugin : string

Préfixe du plugin utilisateur de ezrest et donc fournisseur de la collection.

$filtres : array<string|int, mixed>

Tableau associatif des critères de filtre (couple nom du critère, valeur du critère)

$collection : string

L'identifiant de la collection concernée.

$configuration : array<string|int, mixed>

Configuration de la collection concernée. L'index filtres contient la liste des critères admissibles et l'index module contient le nom du fichier des fonctions de service.

$erreur : array<string|int, mixed>

Tableau initialisé avec les index identifiant l'erreur ou vide si pas d'erreur. Les index mis à jour sont:

  • status : le code de l'erreur HTTP, soit 400
  • type : chaine identifiant l'erreur plus précisément
  • element : nom du critère en erreur
  • valeur : valeur du critère
Return values
bool

true si la valeur est valide, false sinon.

ezrest_collection_verifier_ressource()

Détermine si le type de ressource demandée est valide.

ezrest_collection_verifier_ressource(string $plugin, string $ressource, string $collection, array<string|int, mixed> $configuration, array<string|int, mixed> &$erreur) : bool
Parameters
$plugin : string

Préfixe du plugin utilisateur de ezrest et donc fournisseur de la collection.

$ressource : string

La valeur de la ressource demandée. La ressource appartient à une collection.

$collection : string

L'identifiant de la collection concernée.

$configuration : array<string|int, mixed>

Configuration de la collection de la ressource. L'index ressource identifie le champ attendu pour désigner la ressource et l'index module contient le nom du fichier des fonctions de service.

$erreur : array<string|int, mixed>

Tableau initialisé avec les index identifiant l'erreur ou vide si pas d'erreur. Les index mis à jour sont:

  • status : le code de l'erreur HTTP, soit 400
  • type : chaine identifiant l'erreur plus précisément, soit ressource_nok
  • element : type d'objet sur lequel porte l'erreur, soit ressource
  • valeur : la valeur de la ressource
Return values
bool

true si la valeur est valide, false sinon.

ezrest_indexer()

Construit l'index des collections disponibles avec leur configuration expliquée.

ezrest_indexer() : array<string|int, mixed>
Return values
array<string|int, mixed>

Tableau des configurations des collections disponibles classées par plugin fournisseur.

ezrest_contextualiser()

Construit le contexte à fournir au fichier HTML qui produira le JSON des données de la réponse.

ezrest_contextualiser(string $plugin, string $collection, array<string|int, mixed> $parametres, array<string|int, mixed> $configuration) : array<string|int, mixed>

Cette fonction est utilisée si la méthode de cache choisie dans la configuration de la collection est spip.

Parameters
$plugin : string

Préfixe du plugin utilisateur de ezrest et donc fournisseur de la collection.

$collection : string

L'identifiant de la collection concernée.

$parametres : array<string|int, mixed>

Tableau associatif des paramètres possiblement utiles au contexte. Cet argument est principalement utilisé pour fournir les filtres. Pour une ressource, l'identifiant et la valeur de la ressource sont aussi fournis à l'instar des éventuels filtres.

$configuration : array<string|int, mixed>

Configuration de la collection concernée.

Return values
array<string|int, mixed>

Le tableau de contexte à fournir au fichier HTML.

ezrest_cache_identifier()

Construit l'identifiant relatif du fichier cache (plugin Cache Factory) dans lequel sera stockée la réponse à la requête.

ezrest_cache_identifier(string $plugin, string $type_requete[, string $collection = 'collections' ][, array<string|int, mixed> $parametres = [] ][, array<string|int, mixed> $configuration = [] ]) : array<string|int, mixed>

Le préfixe du plugin sert à définir le sous-dossier de stockage. Le type de requête (collection, ressource, index), l'identifiant de la collection et un éventuellement complément forment les composants du nom du fichier cache.

Parameters
$plugin : string

Préfixe du plugin utilisateur de ezrest et donc fournisseur de la collection.

$type_requete : string

Indique si on demande l'index, une collection ou une ressource.

$collection : string = 'collections'

L'identifiant de la collection concernée.

$parametres : array<string|int, mixed> = []

Tableau associatif des paramètres complémentaires pour calculer l'identifiant. Cet argument est principalement utilisé pour compiler les filtres. Pour une ressource, l'identifiant et la valeur de la ressource sont aussi fournis à l'instar des éventuels filtres.

$configuration : array<string|int, mixed> = []

Configuration de la collection concernée.

Return values
array<string|int, mixed>

Tableau de l'identifiant relatif du fichier cache.

ezrest_conditionner()

Construit le tableau des conditions SQL à appliquer à la collection.

ezrest_conditionner(string $plugin, string $collection, array<string|int, mixed> $filtres, array<string|int, mixed> $configuration) : array<string|int, mixed>
Parameters
$plugin : string

Préfixe du plugin utilisateur de ezrest et donc fournisseur de la collection.

$collection : string

L'identifiant de la collection concernée.

$filtres : array<string|int, mixed>

Tableau associatif des critères de filtre (couple nom du critère, valeur du critère)

$configuration : array<string|int, mixed>

Configuration de la collection concernée.

Return values
array<string|int, mixed>

ezrest_collectionner()

Renvoie les données correspondant à la collection et aux filtres demandés.

ezrest_collectionner(string $plugin, string $collection, array<string|int, mixed> $conditions, array<string|int, mixed> $filtres, array<string|int, mixed> $configuration) : array<string|int, mixed>
Parameters
$plugin : string

Préfixe du plugin utilisateur de ezrest et donc fournisseur de la collection.

$collection : string

L'identifiant de la collection concernée.

$conditions : array<string|int, mixed>

Tableau des conditions SQL à appliquer, compilées à partir des filtres de la requête.

$filtres : array<string|int, mixed>

Tableau associatif des critères de filtre (couple nom du critère, valeur du critère)

$configuration : array<string|int, mixed>

Configuration de la collection concernée.

Return values
array<string|int, mixed>

ezrest_ressourcer()

Renvoie les données correspondant à la ressource demandée.

ezrest_ressourcer(string $plugin, string $collection, string $ressource, array<string|int, mixed> $filtres, array<string|int, mixed> $configuration) : array<string|int, mixed>
Parameters
$plugin : string

Préfixe du plugin utilisateur de ezrest et donc fournisseur de la collection.

$collection : string

L'identifiant de la collection concernée.

$ressource : string

La valeur de la ressource demandée. La ressource appartient à une collection.

$filtres : array<string|int, mixed>

Tableau associatif des critères de filtre (couple nom du critère, valeur du critère)

$configuration : array<string|int, mixed>

Configuration de la collection concernée.

Return values
array<string|int, mixed>

ezrest_post_cache()

Ajoute ou retire le cache créé ou supprimé de l'index des caches REST Factory.

ezrest_post_cache(array<string|int, mixed> $flux) : mixed

Les informations contenues permettent l'affichage précis dans le formulaire de vidage.

Parameters
$flux : array<string|int, mixed>

Tableau des données permettant de caractériser l'appelant et l'action sur les caches.

Tags
pipeline

post_cache

Return values
mixed

Le flux entrant n'est pas modifié.

http_ezrest_erreur_dist()

Traite les erreurs directement détectées par le serveur HTTP abstrait uniquement.

http_ezrest_erreur_dist(int $code, Request $requete, Response $reponse) : Response

Celles-ci sont mises au format de l'API REST ezREST et fournies au client systématiquement en JSON.

Parameters
$code : int

Le code HTTP de l'erreur à générer

$requete : Request

Objet matérialisant la requête faite au serveur.

$reponse : Response

Objet matérialisant la réponse telle qu'initialisée par le serveur HTTP abstrait. Cet objet sera complétée avant d'être retourné par la fonction.

Return values
Response

Retourne l'objet réponse dont le contenu est mis à jour avec les éléments du bloc d'erreur.

http_ezrest_get_index_dist()

Fait un GET sur l'API ezREST seule et renvoie la liste des collections disponibles et les possibilités associées.

http_ezrest_get_index_dist(Request $requete, Response $reponse) : Response

Il ne peut pas y avoir d'erreur à ce niveau de l'API ezREST.

Parameters
$requete : Request

Objet matérialisant la requête faite au serveur.

$reponse : Response

Objet matérialisant la réponse telle qu'initialisée par le serveur HTTP abstrait. Cet objet sera complétée avant d'être retourné par la fonction.

Return values
Response

Retourne l'objet réponse dont le contenu est mis à jour avec les éléments du bloc d'erreur.

http_ezrest_get_collection_dist()

Fait un GET sur une collection gérée par l'API ezREST.

http_ezrest_get_collection_dist(Request $requete, Response $reponse) : Response

La requête est du type /ezrest/ccc et renvoie les objets associées contenus dans la base du serveur. Il est possible de filtrer la collection et de compléter la colelction en utilisant le pipeline post_ezcollection.

Parameters
$requete : Request

Objet matérialisant la requête faite au serveur.

$reponse : Response

Objet matérialisant la réponse telle qu'initialisée par le serveur HTTP abstrait. Cet objet sera complétée avant d'être retourné par la fonction.

Tags
pipeline_appel

post_ezcollection

Return values
Response

Objet réponse complétée (status, contenu de la ressource...). La fonction peut lever une erreur sur le contexte lors de l'appel, la collection ou sur les critères de filtre.

http_ezrest_get_ressource_dist()

Fait un GET sur une ressource d'une collection gérée par l'API ezREST.

http_ezrest_get_ressource_dist(Request $requete, Response $reponse) : Response

La requête est du type /ezrest/ccc/rrr et renvoie l'objet de la base désigné.

Il est possible de rajouter des informations en utilisant le pipeline post_ezressource.

Parameters
$requete : Request

Objet matérialisant la requête faite au serveur.

$reponse : Response

Objet matérialisant la réponse telle qu'initialisée par le serveur HTTP abstrait. Cet objet sera complétée avant d'être retourné par la fonction.

Tags
pipeline_appel

post_ezressource

Return values
Response

Objet réponse complété (status, contenu de la ressource...). La fonction peut lever une erreur sur l'état du serveur, le format de sortie, le type de ressouce et sur l'existence de la ressource demandée.

inc_ezrest_declarer_collections_dist()

Déclare les collections accessibles via HTTP GET.

inc_ezrest_declarer_collections_dist() : array<string|int, mixed>

Par défaut, le plugin ne propose aucune collection.

Tags
pipeline_appel

liste_ezcollection

Return values
array<string|int, mixed>

Description des collections.

Search results