Le projet comporte l'arborescence suivante :

secom.io
├── cli [ **Scripts lancés en ligne de commande** ]
│   ├── directus.php
│   ├── myzen.prod.php
│   └── myzen.dev.php
├── config [ **Fichiers de configuration des différentes entités sur les différents environnements** ]
│   ├── myzen.cfg.php
│   └── myzen.test.cfg.php
├── db [ **Fichiers de définition des collections/items** ]
│   └── myzen
│       ├── collections
│       │   ├── chyro_installs.json
│       │   ├── chyro_programs.json
│       │   ├── directus_relations.json
│       │   ├── languages.json
│       │   ├── programs.json
│       │   └── programs_translations.json
│       └── items
│           └── languages.json
├── directus [ **Copie de travail Git de Directus** ]
│   └── ...
├── directus.secom.io
│   └── config
├── env [ **Fichiers propres aux différents environnements** ]
│   ├── secom.io
│   │   ├── apache
│   │   │   └── apache24.conf
│   │   ├── config [ **directus/config contient des symlinks vers les fichiers de ce répertoire** ]
│   │   │   ├── api.gltv.php
│   │   │   ├── api.melodya.php
│   │   │   ├── api.melody.php
│   │   │   ├── api.museum.php
│   │   │   ├── api.myzen.php
│   │   │   └── api.php
│   │   └── public
│   │       └── admin [ **apache sert ces fichier comme s'ils étaient dans directus/public/admin** ]
│   │           ├── gltv.config.js
│   │           ├── melodya.config.js
│   │           ├── melody.config.js
│   │           ├── museum.config.js
│   │           ├── myzen.config.js
│   │           └── secom.config.js
│   └── test.secom.io
│       └── ...
├── exemples
│   └── ...
├── exports
│   └── ...
├── hooks [ **Contient le code des hooks Directus (inclus automatiquement d'après leur nom) ** ]
│   ├── find_hooks.php
│   └── myzen
│       └── actions
│           ├── item.create.php
│           └── item.delete.programs.php
├── inc [ **Classes utilisant les APIs de Directus, Chyro...** ]
│   ├── api.class.php
│   ├── bot_abstract.class.php
│   ├── bot_directus.class.php
│   ├── bot_entity.class.php
│   ├── bot_myzen.class.php
│   ├── chyro.class.php
│   ├── directus.class.php
│   ├── directus_gltv.class.php
│   ├── directus_myzen.class.php
│   └── myzen.class.php
├── interfaces [ **Contient les sources des interfaces custom** ]
├── pages [ **Contient les sources des pages custom** ]
├── sites [ **Sites annexes** ]
│   └── directus.secom.io [ **Site permettant d'explorer les collections d'un instance Directus**]
│       ├── apache
│       │   └── apache24.conf
│       └── www
│           └── index.php
└── tests
    ├── simpletest [ **Framework de test unitaires** ]
    │   └── ...
    └── unit [ **Test unitaires** ]
        ├── api.test.php
        ├── directus.test.php
        └── ...

Les APIs Chyro et Directus ont quelques points communs : en particulier elles fonctionnent en REST et retournent principalement du JSON.

Les classes PHP développées pour utiliser ces APIs tentent de mutualiser le code des diverses fonctionnalités de ces API au travers du principe d'héritage. De même, les particularités des différentes entités utilisant Chyro pourront se retrouver dans des classes spécifiques dérivant d'une même classe mère délimitant un socle commun.

Au fur et à mesure des développements, certaines méthodes seront sans doute amenées à être déplacées entre les parties communes ou plus spécifiques du code.

Les principales classes de connection aux API s'organisent à travers le schéma d'héritage suivant :

API
├─ Chyro
└─ Directus
   └─ Directus_Myzen
   

Cette classe gère principalement les connections HTTP avec les APIs à travers la librairie Curl. Elle gère également la récupération des données dans les objets PHP ou Json.

Cette classe n'est pas faite pour être instancée directement. Toutefois, il est prévu que son constructeur soit utilisé par les classes qui en dérivent. Celui-ci prend en argument un tableau associatif contenant les paramètres de configuration propres à la classe fille.

Le paramètre 'host' est obligatoire.

Si le tableau passé en paramètre au constructeur contient

debug => true

alors le mode débug sera activé pour l'objet.

Permet d'accéder aux paramètres de configurations passés au constructeur. Si le paramètre n'existe pas, la méthode renvoie NULL. Si de plus celle-ci a été appelée avec le paramètre $needed à TRUE, une erreur sera produite.

Cette méthode ajoute des paramètres GET à une $url passée en paramètres.

Cette méthode permet d'effectuer une requête Curl sur l'API accessible sur le serveur correspondant au paramètre 'host'.

Les paramètres que l'on peut passer à la méthode par le tableau associatif $params sont les suivants :

• url ⇒ (string) (l'URL qui complète le paramètre 'host' défini dans le constructeur)
• ? ⇒ (array) (tableau associatif des paramètres GET qui seront ajoutés à l'URL)
• head ⇒ (bool) (si défini, la requête HTTP sera de type HEAD)
• post ⇒ (array) (requête HTTP de type POST envoyant les données contenues dans le tableau)
• patch ⇒ (array) (idem que 'post' mais avec une requête HTTP de type PATCH)
• delete ⇒ (bool) (si défini, la requête HTTP sera de type DELETE)
• format ⇒ (string) (si format=json, un header “Content-Type: application/json” sera défini, et les données passées en POST ou en PATCH sont encodées en JSON plutôt que d'utiliser la méthode http_build_query.
• cookie ⇒ (array) (les données du tableau associatif passé en paramètre seront définies en tant que cookie)

Si le mode debug est activé lors de l'instanciation de l'objet, les requêtes et réponses Curl faites à l'API seront affichées sur la sortie standard.

Cette méthode permet de récupérer une donnée dans l'objet (ou le tableau associatif) passé en paramètre.

• Si $key vaut NULL, la méthode retournera tout l'objet.
• Si $key est une string, la méthode renverra la propriété de l'objet (ou la valeur du tableau associatif) correspondant à cette clé.
• Si $key est un array de string, la méthode descendra dans l'objet (ou le tableau associatif) en suivant la liste des clés dans $key et retournera la partie de l'objet (ou du tableau) finalement atteinte.

Une erreur sera produite si l'on tente d'accéder à une clé qui n'existe pas.

Même fonctionnement que from_object, mais à partir d'une chaîne au format JSON.

Deux méthodes statiques de cette classe sont utiles pour le débuggage :

Cette méthode permet de retourner une chaine de caractères représentant un objet PHP issu du JSON reçu en réponse des APIs. Lorsque ces objets comportent des tableaux, ceux-ci sont tronqués pour une informations plus condensées, le nombre d'élements étant toutefois indiqué. Le paramètre optionnel $fold_limit permet d'afficher plus ou moins d'éléments dans un tableau. On peux le rendre égal à INF pour tout afficher. De même les chaînes de caratères trop longues seront tronquées, laissant apparaître le début et la fin de la chaîne, ainsi que le nombre de caractères manquants.

Cette méthode affiche le résultat la méthode inspect sur la sorite standard au lieu de le retourner dans une chaîne de caractères.

Cette classe comporte les fonctionnalités propres à l'API Chyro. Si de nouvelles instances de Chyro doivent être prises en charge et que leur API s'avère différente, il faudra sans doute dériver cette classe pour rendre compte de ces spécificités.

L'objet se construit de la façon suivante :

$chyro = new Chryro($params);

où $params est un tableau associatif contenant obligatoirement les clés suivantes :

• host ⇒ (string) (URL de l'API Chyro)
• user ⇒ (string) (Utilisateur Chyro)
• password ⇒ (string) (Mot de passe de l'utilisateur)

En outre, le tableau passé au constructeur peut contenir les clés optionnelles suivantes :

• phpsessid ⇒ (string) (Pour réutiliser une session PHP. Vide par défaut.)
• auto_login ⇒ (bool) (la méthode 'login' sera automatiquement appelée au premier appel de la méthode 'get'. TRUE par défaut)
• auto_reconnect ⇒ (bool) (En cas de réponse vide de l'API Chyro obtenue par la méthode 'get', une tentative de reconnection a lieu, avant que la méthode 'get' soit invoquée de nouveau.)

Permet de se connecter à l'API Chyro, récupère et enregistre l'id de session PHP qui servira aux requêtes ultérieures.

Appelle le endpoint auth/deltoken de l'API Chyro, censée invalider le token (ne semble pas fonctionner : au départ, un paramètre de configuration auto_logout était disponible, déclenchant l'appel automatique de cette méthode dans le destructeur de l'objet, mais ce code a été retiré car il semblait inutile.)

Cette méthode permet de faire une requête générique sur l'API Chyro. Le paramètre 'action' correspond à l'action de l'API Chyro. Le paramètre 'key' permet d'extraire une partie de la réponse (cf. API::from_json) Le paramètre 'params' contient les paramètres qui seront passés à API::curl Le paramètre $format correspond au format tel que spécifié par l'API Chyro (pour le moment uniquement testé avec “/format/json”)

Récupère l'ensemble des programmes classés par ordre croissants de date d'update.

Récupère un programme d'après son ID.

Crée un programme avec les champs du tableau associatif passé en paramètre.

Met à jour un programme avec les champs du tableau associatif passé en paramètre. L'ID du programme doit être contenu dans la clé 'id' de $fields.

Cette classe comporte les fonctionnalités propres à l'API Directus et communes aux différentes entités.

L'objet se construit de la façon suivante :

$directus = new Directus($params);

où $params est un tableau associatif contenant obligatoirement les clés suivantes :

• host ⇒ (string) (URL de l'API Directus)
• email ⇒ (string) (Email du compte utilisateur Directus)
• password ⇒ (string) (Mot de passe du compte utilisateur)

En outre, le tableau passé au constructeur peut contenir les clés optionnelles suivantes :

• token ⇒ (string) (Pour réutiliser un token. Vide par défaut, le token sera alors obtenu automatiquement)
• auto_login ⇒ (bool) (la méthode 'login' sera automatiquement appelée au premier appel de la méthode 'get'. TRUE par défaut)
• auto_reconnect ⇒ (bool) (En cas de réponse false de l'API Directus obtenue par la méthode 'get', une tentative de reconnection a lieu, avant que la méthode 'get' soit invoquée de nouveau.)

Appelle connect() si l'objet n'a pas de token.

Appelle get_token() et stocke le résultat dans l'objet.

Obtient un nouveau token.

Cette méthode permet de faire une requête générique sur l'API Directus. Le paramètre 'endpoint' correspond au endpoint de l'API Directus. Le paramètre 'key' permet d'extraire une partie de la réponse (cf. API::from_json) Le paramètre 'params' contient les paramètres passés à API::curl

Idem que 'get' mais en ajoutant automatiquement

$params['?']['limit'] = 1;

et en retournant le premier élément seulement du 'data' obtenu en réponse si celui-ci est un tableau (sinon, la méthode équivaut à un 'get' classique, avec toutefois un limit=1.)

Par défaut, les résultats de type liste renvoyés par Directus sont limités en nombre d'items. Cette méthode permet d'aggréger les résultats de plusieurs appels à l'API Directus en faisant varier automatiquement le paramètre 'offset' afin d'être sûr de récupérer tout ce qui est en base de donnée. Les paramètres s'utilisent de la même façon que pour un 'get' classique.

Récupère la valeur du champ 'id' de ce qui serait retourné par un 'get_first', le paramètre $data permettant de définir des filtres. Typiquement, si un item de collection peut être identifié à partir d'un certain nombre de champs autres que son ID, cette méthode permet de retrouver l'ID de l'item à partir de ces champs.

Permet de créer ou modifier un item dans une collection. Le paramètre $object peut être un objet PHP ou un tableau associatif. Si la propriété 'id' est définie, la méthode procèdera à une modification (PATCH) sinon à une création (POST).

Idem que la méthode 'save', mais en réalisant une troncature des chaînes de caractères contenues dans $object en fonction de la longueur des champs retournés par la méthode 'fields_lengths'

Idem que la méthode 'save', mais capture une éventuelle erreur Directus de type “Duplicate Item” et ne fait rien dans ce cas. Cette méthode permet de créer un item seulement si il n'existe pas déjà, puis éventuellement de le modifier (tant que les contraintes d'unicités des champs sont respectées).

Le dernier paramètre, s'il est spécifié avec “save_with_strcut” au lieu du “save” par défaut, permet par exemple de combiner les spécificités des méthode “save_if_unique” et “save_with_strcut”.

Cette méthode renvoie un tableau associatif contenant les longeurs des champs d'une collection. Les champs de type “translation” sont gérés, et les champs de la table de traduction sont alors contenus dans un sous-tableau.

Cette méthode retourne le nom du champ de type 'primary_key' (souvent 'id' mais il y a des exceptions, comme pour la tble des langues.) Les clés primaires sur plusieurs champs ne sont pas gérées (est-ce que ça peut exister dans Directus ?)

Retourne la liste des collections, en excluant les collections “internes” de directus (préfixées par “directus_”).

Retourne la liste des relations entre collections.

Récupère la collection correspondant à l'attribut $attr, dans la relation spécifiée par $params. Par exemple, pour une collection 'programs' qui aurait un champ 'program_info' de type 'translation', en relation avec la collection 'programs_translations' :

$api_directus->related("collection_many", [
  'collection_one' => "programs",
  'field_one' => "program_info",
]);

permet de retrouver la collection “programs_translations” en relation avec “programs”.

Permet d'importer les collections définies par les fichiers JSON contenus dans $dir. Les relations contenues dans un éventuel fichier 'directus_relations.json' seront aussi importées.

Recherche un fichier “$collection.json” dans $dir et réalise un 'save_if_unique' sur tous les éléments du tableau JSON contenu dans ce fichier pour la collection donnée.

Supprime de la collection $collection l'item correspondant à l'id $id.

Supprime tous les élements d'une collection.

Si le paramètre optionnel $filter est précisé, il permet de limiter le delete aux items vérifiant les propriétés spécifiées dans ce tableau.

Récupère l'id d'une chyro_install en fonction de la référence passée en paramètre.

Crée une install chyro de référence $ref si elle n'existe pas déjà, et retourne son ID.

Récupère l'ensemble des chyro_programs. Si le paramètres $fields est spécifié, seuls certains champs apparaitront dans la réponse. $fields peut être un tableau ou une chaîne de caractère sous la forme d'une liste de champs séparés par une virgule.

Récupère un chyro_program en fonction de l'ID spécifié.

Récupère un program en fonction de l'ID spécifié.

Un certain nombre de fonctionnalités sont disponibles à partir de scripts exécutables en ligne de commande. Ceux-ci sont rangés dans le répertoire 'cli'. Ces scripts instancient des objets de type bot, dont les classes sont définies dans les fichiers préfixés par “bot_”, et ils utilisent un fichier de configuration parmi ceux rangés dans le répertoire 'config'.

Lorsqu'ils sont lancés sans argument, ou avec '–help', ces scripts affichent la liste des méthodes disponibles.

Ce script execute les méthodes de la classe Bot_Directus (dédinie dans le fichier inc/bot_directus.php). Ce bot contient les méthodes maintenance de l'installation de Directus.

Lance l'installation de Directus et effectue les tâches de la méthode update.

Cette commande effectue : - un git pull du dépot principal - la création dans Directus les liens symboliques vers les fichiers de configuration PHP contenus dans les dossiers 'config' du répertoire 'env' - la compilation des interfaces et des pages custom et la création des liens symboliques correspondants dans Directus.

Cette commande permet de mettre à jour Directus en effectuant les opérations suivantes :

1. Mise à jour du code de Directus avec Git
2. Lancement de l'upgrade de base de donnée de Directus pour tous les “projets” configurés
3. Propriété et droit d'écriture sur les fichiers donnés à l'utilisateur et au groupe www

Ce script éxecute les méthodes de Bot_Myzen qui étend les fonctionnalités de Bot_Entity (qui contiendra les fonctionnalités communes aux différentes entités).

Le script se décline en réalité selon les environnements en myzen.prod.php, myzen.dev.php, etc. Pour simplifier, nous utiliserons ci-dessous cli/myzen.php.

La plupart des méthodes peuvent être lancées en rajoutant l'option –debug qui rajoute alors automatiquement la propriété debug ⇒ true aux configurations utilisées, ce qui affiche par exemple sur la sortie standard les requêtes et réponses Curl de communication à travers les APIs Directus et Chyro.

Installe la base de données (collections et items) d'après les fichiers du répertoire db.

Affiche le liste des collections.

Permet de vider une collection.

Importe les chyro_programs depuis les instances de Chyro configurées. (Utilisé dans le processus de synchro.)

Importe les programs à partir des chyro_programs. (Utilisé dans le processus de synchro.)