REST Factory

Simplifier la mise en place d’une API REST

Version 1.2.5 (9bcdc28)

Packages

Reports

Indices

Files

Documentation générée le 22 01 2024 à 08h15

Documentation

Packages

Application
SPIP

Functions

ezrest_cache_configurer() : array<string, 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, 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, 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, mixed>: Initialise le contenu d'une réponse qui se présente comme un tableau associatif.
ezrest_reponse_informer_plugin() : array<string, mixed>: Complète l'initialisation du contenu d'une réponse avec des informations sur le plugin utilisateur.
ezrest_reponse_expliquer_erreur() : array<string, 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, mixed>: Construit l'index des collections disponibles avec leur configuration expliquée.
ezrest_contextualiser() : array<string, mixed>: Construit le contexte à fournir au fichier HTML qui produira le JSON des données de la réponse.
ezrest_cache_identifier() : array<string, 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() : array<string|int, 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.
cache_reponse_vider() : bool: Vide, pour un plugin utilisateur donné, les caches du type `reponse` éventuellement filtrés.
inc_ezrest_declarer_collections_dist() : array<string|int, mixed>: Déclare les collections accessibles via HTTP GET.

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, 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, 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, mixed> $valeurs, array<string|int, mixed> $options, array<string, mixed> $configuration) : array<string, 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, 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, mixed>: Configuration complète des caches du plugin utilisateur lue à partir de la meta de stockage.

Return values

array<string, 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, mixed> $valeurs, array<string|int, mixed> $options, array<string, mixed> $configuration) : array<string, 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, 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, mixed>: Configuration complète des caches du plugin utilisateur lue à partir de la meta de stockage.

Return values

array<string, 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, 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, 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, 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, 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, mixed> $contenu) : array<string, 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, mixed>: Le contenu de la réponse initialisé par ezrest_reponse_initialiser_contenu.

Return values

array<string, 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, mixed> $erreur[, null|string $collection = '' ]) : array<string, mixed>

Parameters

$plugin : string: Préfixe du plugin utilisateur de ezrest et donc fournisseur de la collection.
$erreur : array<string, mixed>: Tableau initialisé avec les éléments de base de l'erreur (status, type, element et valeur).
$collection : null|string = '': Identifiant de la collection

Return values

array<string, 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, 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, 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, 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, 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, mixed> $filtres, string $collection, array<string, mixed> $configuration, array<string, 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, 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, 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, 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, mixed> $configuration, array<string, 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. On considère que la ressource est passée comme une chaine, c'est au plugin utilisateur de connaitre son type réel.

$collection : string

L'identifiant de la collection concernée.

$configuration : array<string, 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, 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, mixed>

Return values

array<string, 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, mixed> $parametres, array<string, mixed> $configuration) : array<string, 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, 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, mixed>: Configuration de la collection concernée.

Return values

array<string, 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[, null|string $collection = 'collections' ][, null|array<string, mixed> $parametres = [] ][, null|array<string, mixed> $configuration = [] ]) : array<string, 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 : null|string = 'collections': L'identifiant de la collection concernée.
$parametres : null|array<string, 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 : null|array<string, mixed> = []: Configuration de la collection concernée.

Return values

array<string, 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, mixed> $filtres, array<string, 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, mixed>: Tableau associatif des critères de filtre (couple nom du critère, valeur du critère)
$configuration : array<string, mixed>: Configuration de la collection concernée.

Return values

array<string|int, mixed> —

Tableau des conditions SQL

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, mixed> $filtres, array<string, 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, mixed>: Tableau associatif des critères de filtre (couple nom du critère, valeur du critère)
$configuration : array<string, mixed>: Configuration de la collection concernée.

Return values

array<string|int, mixed> —

Données correspondant à la requête sur la collection

ezrest_ressourcer()

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


    
                    ezrest_ressourcer(string $plugin, string $collection, string $ressource, array<string, mixed> $filtres, array<string, 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. On considère que la ressource est passée comme une chaine, c'est au plugin utilisateur de connaitre son type réel.
$filtres : array<string, mixed>: Tableau associatif des critères de filtre (couple nom du critère, valeur du critère)
$configuration : array<string, mixed>: Configuration de la collection concernée.

Return values

array<string|int, mixed> —

Données correspondant à la requête sur la ressource

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) : array<string|int, 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.

Return values

array<string|int, 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.

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.

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.

cache_reponse_vider()

Vide, pour un plugin utilisateur donné, les caches du type `reponse` éventuellement filtrés.


    
                    cache_reponse_vider(string $plugin[, null|string $type_requete = '' ][, null|string $collection = '' ]) : bool

Parameters

$plugin : string: Préfixe du plugin utilisateur de ezrest et donc fournisseur de la collection.
$type_requete : null|string = '': Indique si on demande l'index, une collection ou une ressource.
$collection : null|string = '': L'identifiant de la collection concernée.

Return values

bool —

true si la suppression s'est bien passée, false sinon.

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.

Return values

array<string|int, mixed> —

Description des collections.

Documentation

Table of Contents

Packages

Functions

Functions

ezrest_cache_configurer()

Parameters

Return values

ezrest_reponse_cache_formulaire_charger()

Parameters

Tags

Return values

ezrest_index_cache_formulaire_charger()

Parameters

Tags

Return values

ezrest_api_verifier_contexte()

Parameters

Tags

Return values

ezrest_reponse_initialiser_contenu()

Parameters

Tags

Return values

ezrest_reponse_informer_plugin()

Parameters

Tags

Return values

ezrest_reponse_expliquer_erreur()

Parameters

Tags

Return values

ezrest_reponse_construire()

Parameters

Return values

ezrest_collection_verifier()

Parameters

Tags

Return values

ezrest_collection_verifier_filtre()

Parameters

Tags

Return values

ezrest_collection_verifier_ressource()

Parameters

Tags

Return values

ezrest_indexer()

Return values

ezrest_contextualiser()

Parameters

Return values

ezrest_cache_identifier()

Parameters

Return values

ezrest_conditionner()

Parameters

Tags

Return values

ezrest_collectionner()

Parameters

Tags

Return values

ezrest_ressourcer()

Parameters

Tags

Return values

ezrest_post_cache()

Parameters

Tags

Return values

http_ezrest_erreur_dist()

Parameters

Tags

Return values

http_ezrest_get_index_dist()

Parameters

Tags

Return values

http_ezrest_get_collection_dist()