2016-04-18 08:30:40 +00:00
< ? php
2016-10-18 13:11:37 +00:00
namespace api\module ;
2016-04-18 08:30:40 +00:00
use \manager\ManagerError ;
class module {
2016-04-30 09:33:01 +00:00
/* PERMET DE TESTER L ' API
*
*/
2016-04-18 08:30:40 +00:00
public static function method (){
2016-09-12 16:04:53 +00:00
return [
2016-04-18 09:30:38 +00:00
'ModuleError' => ManagerError :: Success ,
'ReceivedArguments' => func_get_args ()
2016-09-12 16:04:53 +00:00
];
2016-04-18 08:30:40 +00:00
}
2016-04-30 09:33:01 +00:00
/* PERMET DE TESTER UNE L ' ORDRE DES PARAMÈTRES
*
*/
2016-04-18 09:30:38 +00:00
public static function phpunitParams ( $params ){
extract ( $params );
2016-09-12 16:04:53 +00:00
return [
2016-04-18 09:30:38 +00:00
'ModuleError' => ManagerError :: Success ,
'p1' => $p1 ,
'p2' => $p2
2016-09-12 16:04:53 +00:00
];
2016-04-18 09:30:38 +00:00
}
2016-04-30 09:33:01 +00:00
/* RENVOIE UNE DESCRIPTION EN MARKDOWN DES MODULES DE L ' API
*
* @ return markdown < String > Description des modules
*
*/
public static function markdown (){
/* [ 1 ] Récupération de la configuration
=========================================================*/
// On récupère le fichier et on le parse
2016-10-18 13:11:37 +00:00
$modules = json_decode ( file_get_contents ( __CONFIG__ . '/modules.json' ), true );
2016-04-30 09:33:01 +00:00
// Gestion de l'erreur de parsage
if ( $modules == null )
2016-09-12 16:04:53 +00:00
return [ 'ModuleError' => ManagerError :: ParsingFailed ];
2016-04-30 09:33:01 +00:00
/* [ 2 ] Mise en forme de la liste des modules
=========================================================*/
2016-06-03 08:58:01 +00:00
$markdown = " ## Module List \n " ;
2016-04-30 09:33:01 +00:00
foreach ( $modules as $moduleName => $moduleData )
2016-06-03 08:58:01 +00:00
$markdown .= " - $moduleName\n " ;
2016-04-30 09:33:01 +00:00
/* [ 3 ] Mise en forme des méthodes des modules
=========================================================*/
2016-06-03 08:58:01 +00:00
$markdown .= " ---- \n ## Method List & Description \n " ;
2016-04-30 09:33:01 +00:00
$count = 1 ;
foreach ( $modules as $moduleName => $moduleData ){
2016-06-03 08:58:01 +00:00
$markdown .= " ### $count - ' $moduleName ' methods \n " ;
2016-04-30 09:33:01 +00:00
foreach ( $moduleData as $methodName => $methodData )
2016-06-03 08:58:01 +00:00
$markdown .= " ` $methodName ` - " . $methodData [ 'description' ] . " \n " ;
2016-04-30 09:33:01 +00:00
2016-06-03 08:58:01 +00:00
$markdown .= " ---- \n " ;
2016-04-30 09:33:01 +00:00
$count ++ ;
}
/* [ n ] Gestion du retour
=========================================================*/
2016-09-12 16:04:53 +00:00
return [
2016-04-30 09:33:01 +00:00
'ModuleError' => ManagerError :: Success ,
2016-09-12 16:04:53 +00:00
'headers' => [
2016-06-03 08:58:01 +00:00
'Content-Type' => 'text/markdown; charset=utf-8' ,
'Content-Transfer-Encoding' => 'binary' ,
'Content-Disposition' => 'attachment; filename=NxTIC.apib' ,
'Pragma' => 'no-cache' ,
'Expires' => '0'
2016-09-12 16:04:53 +00:00
],
2016-06-03 08:58:01 +00:00
'body' => $markdown
2016-09-12 16:04:53 +00:00
];
2016-04-30 09:33:01 +00:00
}
2016-04-18 09:30:38 +00:00
2016-04-18 08:30:40 +00:00
2016-06-03 08:58:01 +00:00
/* RENVOIE UNE DOC API_BLUEPRINT DE L ' API
*
* @ return apiBlueprint < String > Description des modules au format API Blueprint
*
*/
public static function apiBlueprint (){
2016-06-04 11:52:48 +00:00
/* [ 0 ] Récupération de la configuration
2016-06-03 08:58:01 +00:00
=========================================================*/
// On récupère le fichier et on le parse
2016-10-18 13:11:37 +00:00
$modules = json_decode ( file_get_contents ( __CONFIG__ . '/modules.json' ), true );
2016-04-18 08:30:40 +00:00
2016-06-03 08:58:01 +00:00
// Gestion de l'erreur de parsage
if ( $modules == null )
2016-09-12 16:04:53 +00:00
return [ 'ModuleError' => ManagerError :: ParsingFailed ];
2016-06-03 08:58:01 +00:00
2016-06-04 11:52:48 +00:00
/* [ 1 ] Début du fichier custom
=========================================================*/
$content = " FORMAT: 1A \n " ;
$content .= " HOST: https://socioview.xdrm.io/api/ \n \n " ;
$content .= " # NxTIC API \n " ;
$content .= " API de la plateforme d'étude **NxTIC**, cette documentation présentera toutes les méthodes accessibles depuis la plateforme elle-même et depuis un logiciel tiers. \n " ;
$content .= " La plateforme **NxTIC** est une plateforme d'étude sociale développé par Adrien Marquès _(xdrm-brackets)_ pour un laboratoire de sociologie du _CNRS_. \n " ;
$content .= " Elle a pour objectif l'acquisition, la visualisation et l'extraction de données relationnelles. \n " ;
2016-06-04 11:56:07 +00:00
$content .= " > Cette plateforme est temporairement hébergée sur https://socioview.xdrm.io/. \n \n " ;
2016-06-04 11:52:48 +00:00
$content .= " ## Structure et fonctionnement \n " ;
$content .= " Le fonctionnement est basé sur une délégation à 2 niveaux : des __modules__ contenant des __méthodes__. \n \n " ;
2016-06-04 11:56:07 +00:00
$content .= " *** \n \n " ;
2016-06-04 11:52:48 +00:00
$content .= " ### Paramètres \n " ;
$content .= " Tous les paramètres doivent être envoyés en `multipart/form-data`. \n \n " ;
$content .= " 1. Chacun formatté en `json` \n " ;
$content .= " 2. Portant le `nom` défini dans la documentation \n " ;
$content .= " 3. L'ordre n'a pas d'importance \n " ;
$content .= " 4. Respectant le `type` défini dans la documentation (cf. [Types](#introduction/types-de-donnees)) \n \n " ;
$content .= " > **Note:** Les `paramètres URI` ne correspondent pas aux paramètres URI. \n " ;
2016-06-04 11:56:07 +00:00
$content .= " Ils servent à expliciter les paramètres et leurs types, et correspondent aux variables notées ` { nomVar}` dans le corps de la requête. \n \n " ;
2016-06-04 11:52:48 +00:00
$content .= " ### Réponses \n \n " ;
$content .= " #### A. Les réponses seront formattées en json et contiendront: \n \n " ;
$content .= " 1. `ModuleError` - Le code de l'erreur \n " ;
$content .= " 2. `ErrorDescription` - La description de l'erreur \n \n " ;
$content .= " **** \n \n " ;
$content .= " #### B. Codes `HTTP` et leur signification. \n \n " ;
$content .= " |Status|Code HTTP| \n " ;
$content .= " |---|---| \n " ;
$content .= " |OK|`200` - Success| \n " ;
2016-06-04 11:56:07 +00:00
$content .= " |Erreur|`417` - Erreur quelconque| \n \n " ;
2016-06-04 11:52:48 +00:00
$content .= " ## Types de données \n \n " ;
$content .= " ### Types Simples \n " ;
$content .= " |Type|Exemple|Description| \n " ;
$content .= " |---|---|---| \n " ;
$content .= " |`mixed`|`[9, \" a \" ]`, ` \" a \" `|Type quelconque (peut être simple ou composé)| \n " ;
$content .= " |`id`|`10`, ` \" 23 \" `|Nombre entier positif compris entre `0` et `2147483647`| \n " ;
$content .= " |`text`|` \" Hello! \" `|Chaine de caractères de longueur quelconque (peut être vide)| \n " ;
$content .= " |`mail`|` \" a.b@c.def \" `|Adresse mail avec une syntaxe valide| \n " ;
$content .= " |`number`|`0102030405`|Numéro de téléphone valide suivant les formats : `06`, `+336`, `+33 6`| \n " ;
$content .= " |`array`|`[1, 3]`|Tableau quelconque non vide| \n " ;
$content .= " |`boolean`|`true`, `false`|Booléen| \n " ;
2016-06-04 11:56:07 +00:00
$content .= " |`varchar(a,b)`|` \" Hello! \" `|Chaine de caractères de taille comprise entre `a` et `b` (inclus)| \n \n " ;
2016-06-04 11:52:48 +00:00
$content .= " ### Type composé : array \n \n " ;
$content .= " |Type|Sous-Type|Description| \n " ;
$content .= " |---|---|---| \n " ;
$content .= " |`array<mixed>`|`mixed`|Tableau contenant uniquement des données de type `mixed`| \n " ;
$content .= " |`array<id>`|`id`|Tableau contenant uniquement des données de type `id`| \n " ;
$content .= " |`array<text>`|`text`|Tableau contenant uniquement des données de type `text`| \n " ;
$content .= " |`array<mail>`|`mail`|Tableau contenant uniquement des données de type `mail`| \n " ;
$content .= " |`array<number>`|`number`|Tableau contenant uniquement des données de type `number`| \n " ;
$content .= " |`array<array>`|`array`|Tableau contenant uniquement des données de type `array`| \n " ;
$content .= " |`array<boolean>`|`boolean`|Tableau contenant uniquement des données de type `boolean`| \n " ;
$content .= " |`array<varchar(a,b)>`|`varchar(a,b)`|Tableau contenant uniquement des données de type `varchar(a,b)`| \n \n " ;
$content .= " > **Note:** Il est possible de chainer le type `array` autant de fois que nécessaire. \n " ;
$content .= " **Ex.:** `array<array<id>>` - Soit un tableau contenant des tableaux contenant exclusivement des données de type `id`. \n " ;
2016-06-06 09:37:21 +00:00
$content .= " \n \n \n \n \n " ;
2016-06-03 08:58:01 +00:00
/* [ 2 ] Pour chaque module
=========================================================*/
foreach ( $modules as $module => $methods ){
$content .= " ## $module [/ $module ] \n \n " ;
/* [ 3 ] Pour chaque méthode
=========================================================*/
foreach ( $methods as $methName => $method ){
2016-06-03 13:12:01 +00:00
/* (1) Description */
2016-06-03 08:58:01 +00:00
$content .= " ### $methName [POST / $module / $methName ] \n \n " ;
$content .= $method [ 'description' ] . " \n " ;
if ( count ( $method [ 'permissions' ]) > 0 )
2016-06-03 13:12:01 +00:00
$content .= '> Permissions `' . implode ( '``' , $method [ 'permissions' ]) . " ` \n \n " ;
2016-06-03 15:29:37 +00:00
// Liste des paramètres
if ( isset ( $method [ 'parameters' ]) && count ( $method [ 'parameters' ]) > 0 ){
// On explicite tous les paramètres
$content .= " + Parameters \n \n " ;
foreach ( $method [ 'parameters' ] as $argName => $argument ){
$optional = isset ( $argument [ 'optional' ]) && $argument [ 'optional' ] === true ;
2016-06-04 09:06:36 +00:00
$content .= " + $argName ( ${ argument['type'] } , " . ( $optional ? 'optional' : 'required' ) . " ) - ${ argument['description'] } \n " ;
2016-06-03 15:29:37 +00:00
}
$content .= " \n " ;
}
2016-06-03 13:12:01 +00:00
/* (2) Requête */
2016-06-04 09:06:36 +00:00
$content .= " + Request (multipart/form-data; boundary=xxxBOUNDARYxxx) \n \n " ;
2016-06-03 13:12:01 +00:00
2016-06-03 15:29:37 +00:00
// Header
$content .= " + Headers \n \n " ;
2016-06-04 09:06:36 +00:00
$content .= " Authorization: Digest { yourAccessToken} \n " ;
$content .= " Cache-Control: no-cache \n " ;
2016-06-03 13:12:01 +00:00
2016-06-03 15:29:37 +00:00
if ( isset ( $method [ 'parameters' ]) && count ( $method [ 'parameters' ]) > 0 ){
2016-06-03 13:12:01 +00:00
2016-06-03 15:29:37 +00:00
// Body
2016-06-04 09:06:36 +00:00
$content .= " + Body \n \n " ;
2016-06-03 15:29:37 +00:00
foreach ( $method [ 'parameters' ] as $argName => $argument ){
2016-06-04 09:06:36 +00:00
$content .= " --xxxBOUNDARYxxx \n " ;
$content .= " Content-Disposition: form-data; name= \" $argName\ " \n " ;
$content .= " Content-Type: application/json \n \n " ;
2016-06-04 09:17:03 +00:00
$content .= " { " . $argName . " } \n " ;
2016-06-03 13:12:01 +00:00
}
2016-06-04 09:06:36 +00:00
2016-06-04 09:17:03 +00:00
$content .= " --xxxBOUNDARYxxx-- \n " ;
2016-06-03 15:29:37 +00:00
// Schema
$content .= " + Schema \n \n " ;
$content .= " { \n " ;
foreach ( $method [ 'parameters' ] as $argName => $argData )
2016-06-04 09:06:36 +00:00
$content .= " \" $argName\ " : @ $argName\n " ;
$content .= " } \n " ;
2016-06-03 15:29:37 +00:00
}
2016-06-03 08:58:01 +00:00
2016-06-03 13:12:01 +00:00
/* (3) Réponse */
2016-06-04 09:06:36 +00:00
$content .= " \n + Response 200 (application/json) \n \n " ;
2016-06-03 13:28:17 +00:00
if ( isset ( $method [ 'output' ]) && count ( $method [ 'output' ]) > 0 ){
2016-06-03 15:29:37 +00:00
// Body
$content .= " + Body \n \n " ;
2016-06-03 13:12:01 +00:00
$content .= " { \n " ;
2016-06-03 15:29:37 +00:00
foreach ( $method [ 'output' ] as $outName => $outData )
$content .= " \" $outName\ " : @ $outName\n " ;
2016-06-04 09:06:36 +00:00
$content .= " } \n " ;
2016-06-03 08:58:01 +00:00
2016-06-03 15:29:37 +00:00
// Schema
$content .= " + Schema \n \n " ;
$content .= " { \n " ;
foreach ( $method [ 'output' ] as $outName => $outData )
$content .= " \" $outName\ " : @ $outName\n " ;
2016-06-04 09:06:36 +00:00
$content .= " } \n " ;
2016-06-03 15:29:37 +00:00
// On explicite tous les paramètres
$content .= " + Attributes (object) \n \n " ;
foreach ( $method [ 'output' ] as $outName => $outData )
$content .= " + $outName ( ${ outData['type'] } ) - ${ outData['description'] } \n " ;
2016-06-03 13:28:17 +00:00
}
2016-06-03 15:29:37 +00:00
$content .= " \n \n " ;
2016-06-03 08:58:01 +00:00
}
}
2016-09-12 16:04:53 +00:00
return [
2016-06-03 08:58:01 +00:00
'ModuleError' => ManagerError :: Success ,
2016-09-12 16:04:53 +00:00
'headers' => [
2016-06-03 08:58:01 +00:00
'Content-Type' => 'application/octet-stream; charset=utf-8' ,
'Content-Transfer-Encoding' => 'binary' ,
'Content-Disposition' => 'attachment; filename=NxTIC.apib' ,
'Pragma' => 'no-cache' ,
'Expires' => '0'
2016-09-12 16:04:53 +00:00
],
2016-06-03 08:58:01 +00:00
'body' => $content
2016-09-12 16:04:53 +00:00
];
2016-06-03 08:58:01 +00:00
}
2016-04-18 08:30:40 +00:00
}
2016-04-30 09:33:01 +00:00
2016-04-18 08:30:40 +00:00
?>