README

Agora Learning - Client PHP

Client PHP officiel pour l'API Agora Learning. Il permet à des applications tierces de gérer des ressources de formation (personnes, apprenants, formateurs, sociétés, sessions, inscriptions) via une interface orientée objet, sans avoir à manipuler directement les requêtes HTTP ou les jetons d'authentification.

Table des matières

Installation

composer require logipro/agora-learning-php

Voir docs/installation.md pour les prérequis détaillés.

Quick Start

<?php
require_once __DIR__ . '/vendor/autoload.php';

use AgoraLearningPhp\AgoraLearningClient;
use AgoraLearningPhp\DTO\Input\Learner\LearnerInput;
use AgoraLearningPhp\Identifier\ExternalId;

$client = new AgoraLearningClient(
    'https://votre-instance.example.com', // TODO: à adapter
    'votre_cle_api'                       // TODO: à adapter
);

// Vérifier que l'API est joignable
$ping = $client->ping();
if ($ping->getStatusCode() !== 200) {
    throw new \RuntimeException(
        'Impossible de joindre l\'API Agora (HTTP ' . $ping->getStatusCode() . ')'
    );
}

// Créer un apprenant
$created = $client->createLearner(new LearnerInput(
    new ExternalId('MonERP', 'L-41'),
    'Dupont',
    'Marie',
    'marie.dupont@example.com', // recoverEmail
    'marie.dupont@example.com'  // email
));

echo $created->agoraId->getId(); // identifiant Agora de l'apprenant créé

// Les créations ne renvoient que les identifiants : relire l'objet complet si besoin
$learner = $client->getLearner($created->agoraId);

Ressources disponibles

Ressource	Lecture	Création	Remplacement (PUT)	Modification partielle (PATCH)	Suppression (DELETE)
Auth	`ping()`
Person	`getPerson()`, `getCollectionPerson()`	`createPerson()`	`replacePerson()`	`patchPerson()`	`deletePerson()`
Trainer	`getTrainer()`, `getCollectionTrainer()`	`createTrainerEmployee()`, `createTrainerFree()`	`replaceTrainerEmployee()`, `replaceTrainerFree()`	`patchTrainerEmployee()`, `patchTrainerFree()`	`deleteTrainer()`
Learner	`getLearner()`, `getCollectionLearner()`	`createLearner()`	`replaceLearner()`	`patchLearner()`	`deleteLearner()`
Society	`getSociety()`, `getCollectionSociety()`	`createSociety()`	`replaceSociety()`	`patchSociety()`	`deleteSociety()`
Session	`getSession()`, `getCollectionSession()`	`createSession()`	`replaceSession()`	`patchSession()`	`deleteSession()`
Enrollment	`getEnrollment()`, `getCollectionEnrollmentFromSession()`, `getCollectionEnrollmentFromLearner()`, `getEnrollmentFromSessionAndLearner()`	`createEnrollment()`			`deleteEnrollment()`, `deleteEnrollmentFromSessionAndLearner()`, `deleteCollectionEnrollmentFromSession()`, `deleteCollectionEnrollmentFromLearner()`
Program	`getProgram()`		`replaceProgram()`		`deleteProgram()` (vide le programme)

Les suppressions ne renvoient rien (réponse 204) et lèvent une AgoraLearningClientException de code 404 si l'objet n'existe pas.

Une personne, une société, un formateur ou une session peut aussi être détaché de l'application source avec detachPerson(), detachSociety(), detachTrainer() ou detachSession() (PATCH /{ressource}/{id}/detach, réponse 204) : il reste sur Agora mais n'y est plus lié.

Les lectures, modifications et suppressions acceptent un AgoraId ou un ExternalId ; les créations prennent un ExternalId obligatoire. Créations et modifications renvoient un CreatedOutput (agoraId, externalId).

replace*() (PUT) reprend le DTO de création et remplace l'objet : un champ facultatif non renseigné est vidé.
patch*() (PATCH, application/merge-patch+json) prend un DTO de patch (PersonPatchInput, FixedSessionPatchInput…) : seuls les champs renseignés par ses setters sont modifiés, null vide le champ.

Consultez docs/usage.md pour un exemple complet par méthode.

Exemples exécutables

Le dossier examples/ contient un fichier PHP autonome par méthode, prêt à être lancé en ligne de commande.

Configuration

cp examples/config.php.dist examples/config.php
# Éditer examples/config.php et renseigner l'URL et la clé API

examples/config.php est ignoré par git - ne pas le versionner.

Lancer un exemple

php examples/ping.php
php examples/person/get_collection.php
php examples/society/create.php
# etc.

Avec Docker, sur une instance Agora locale

Si l'URL de examples/config.php pointe vers une instance Agora qui tourne dans Docker sur la même machine (par exemple http://agoralearning-local/phoenix), le nom d'hôte n'est connu que sur le réseau Docker agora-network. Un conteneur lancé par docker compose run n'est pas sur ce réseau et échoue avec Could not resolve host.

Lancer l'exemple avec docker run en le rattachant à ce réseau :

# PHP 7.4 (dépendances dans vendor74/)
docker run --rm --network agora-network \
  -v "$PWD":/app -v "$PWD/vendor74":/app/vendor -w /app \
  agora-learning-php-php74 php examples/ping.php

# PHP 8.2 (dépendances dans vendor/)
docker run --rm --network agora-network \
  -v "$PWD":/app -w /app \
  agora-learning-php-php php examples/ping.php

Les images doivent avoir été construites (docker compose build) et les dépendances installées dans le dossier vendor* correspondant. La stack Agora doit être démarrée pour que le réseau agora-network existe.

Arborescence

examples/
├── config.php.dist          ← modèle à copier
├── ping.php
├── person/
│   ├── get_collection.php
│   ├── get_one.php
│   ├── get_one_by_agora_id.php
│   ├── create.php
│   ├── replace.php
│   ├── patch.php
│   └── delete.php
├── trainer/
│   ├── get_collection.php
│   ├── get_one.php
│   ├── create_employee.php
│   ├── create_free.php
│   ├── replace_employee.php
│   ├── replace_free.php
│   ├── patch_employee.php
│   ├── patch_free.php
│   └── delete.php
├── learner/
│   ├── get_collection.php
│   ├── get_one.php
│   ├── create.php
│   ├── replace.php
│   ├── patch.php
│   └── delete.php
├── society/
│   ├── get_collection.php
│   ├── get_one.php
│   ├── create.php
│   ├── replace.php
│   ├── patch.php
│   └── delete.php
├── session/
│   ├── get_collection.php
│   ├── get_one.php
│   ├── get_one_by_agora_id.php
│   ├── get_one_by_external_id.php
│   ├── create_fixed.php
│   ├── create_opened.php
│   ├── replace_fixed.php
│   ├── patch_fixed.php
│   ├── patch_opened.php
│   └── delete.php
├── program/
│   └── delete.php
└── enrollment/
    ├── get_from_session.php
    ├── get_from_learner.php
    ├── get_one.php
    ├── get_from_session_and_learner.php
    ├── create.php
    ├── delete.php
    ├── delete_from_session_and_learner.php
    ├── delete_from_session.php
    └── delete_from_learner.php

Gestion des erreurs

Voir la section dédiée dans docs/usage.md#gestion-des-erreurs.

Développement

Prérequis

PHP 7.4+ et Composer installés localement, ou Docker (aucun prérequis PHP local dans ce cas).

Outils disponibles

Commande	Outil	Rôle
`composer cs-check`	php-cs-fixer	Vérifie le style PSR-12 sans modifier les fichiers
`composer cs-fix`	php-cs-fixer	Corrige automatiquement les violations de style
`composer phpstan`	PHPStan niveau 10	Analyse statique du répertoire `src/`
`composer test`	PHPUnit 9	Lance tous les tests (unitaires + intégration)
`composer test-unitaire`	PHPUnit 9	Lance les tests unitaires (`tests/unit/`)
`composer test-integration`	PHPUnit 9	Lance les tests d'intégration (`tests/integration/`) contre une vraie instance Agora
`composer infection`	Infection 0.29	Tests de mutation (suite `Unit`, 4 threads)
`composer qa`	-	Enchaîne cs-check, phpstan et test-unitaire

Sans Docker

# Installer les dépendances
composer install

# Tous les contrôles qualité
composer qa

# Tous les tests (unitaires + intégration)
composer test

# Tests unitaires seuls
composer test-unitaire

# Tests d'intégration (instance Agora configurée dans .env.local)
composer test-integration

# Tests de mutation
composer infection

Avec Docker

Trois services sont disponibles : php (PHP 8.2, par défaut, dépendances dans vendor/), php85 (PHP 8.5, dépendances dans vendor85/) et php74 (PHP 7.4, dépendances dans vendor74/).

Construire les images

# Toutes les images en une commande
docker compose build

# Une image spécifique
# PHP 8.2 (par défaut)
docker compose build php

# PHP 8.5
docker compose build php85

# PHP 7.4
docker compose build php74

Accéder au docker

docker exec -ti agora-learning-php-php-1 /bin/bash

Installer les dépendances

# PHP 8.2 (par défaut), dans vendor/
docker compose run --rm php composer update

# PHP 8.5, dans vendor85/
docker compose run --rm php85 composer update

# PHP 7.4, dans vendor74/
docker compose run --rm php74 composer update

Contrôles qualité

# PHP 8.2 (par défaut)
docker compose run --rm php composer qa

# PHP 8.5
docker compose run --rm php85 composer qa

# PHP 7.4
docker compose run --rm php74 composer qa

Tests unitaires

# PHP 8.2 (par défaut)
docker compose run --rm php composer test-unitaire

# PHP 8.5
docker compose run --rm php85 composer test-unitaire

# PHP 7.4
docker compose run --rm php74 composer test-unitaire

Tests d'intégration

Ils appellent une vraie instance Agora et y créent des données : utilisez une instance de développement, jamais la production.

La configuration se fait par deux variables :

Variable	Rôle	Où la définir
`AGORA_BASE_URL`	URL racine de l'instance, vue depuis le conteneur (sans `/api/external/v1`)	valeur par défaut dans `.env`, à surcharger dans `.env.local`
`AGORA_API_KEY`	clé API externe de l'instance	`.env.local` uniquement

.env.local n'est pas versionné. composer install et composer update le créent à partir de .env.local.dist s'il n'existe pas. Ordre de priorité : variable d'environnement, puis .env.local, puis .env.

Si une variable est vide ou si l'instance n'est pas joignable, les tests sont ignorés (skipped) avec le motif.

docker compose run --rm php composer test-integration

Style de code

# Vérifier sans modifier
docker compose run --rm php composer cs-check

# Appliquer les corrections
docker compose run --rm php composer cs-fix

Analyse statique

docker compose run --rm php composer phpstan

Tests de mutation (Infection)

# PHP 8.2 (par défaut)
docker compose run --rm php composer infection

# PHP 8.5
docker compose run --rm php85 composer infection

# PHP 7.4
docker compose run --rm php74 composer infection

Tests de mutation — Infection

La configuration est dans infection.json5 :

Cible : répertoire src/
Framework : PHPUnit, suite Unit
Mutateurs : ensemble @default
Logs générés dans var/infection/ :
- infection.log — détail textuel
- infection.html — rapport HTML interactif
- summary.log — résumé MSI

# Lancer les tests de mutation (4 threads)
composer infection

# Avec un seuil MSI minimal (ex : 80 %)
vendor/bin/infection --threads=4 --min-msi=80 --min-covered-msi=80

# Cibler un seul fichier source
vendor/bin/infection --threads=4 --filter=src/Service/Learner/Learner.php

Style de code

La configuration est dans .php-cs-fixer.php :

Ruleset @PSR12
declare(strict_types=1) obligatoire
Imports triés alphabétiquement, imports inutilisés supprimés
Cache dans .php-cs-fixer.cache (ignoré par git)

Analyse statique

La configuration est dans phpstan.neon — niveau , cible src/.

Tests unitaires

La configuration est dans phpunit.xml.dist. La suite Unit pointe sur tests/unit/.

logipro / agora-learning-php

Package info

Security

Statistics

README

Agora Learning - Client PHP

Table des matières

Installation

Quick Start

Ressources disponibles

Exemples exécutables

Configuration

Lancer un exemple

Avec Docker, sur une instance Agora locale

Arborescence

Gestion des erreurs

Développement

Prérequis

Outils disponibles

Sans Docker

Avec Docker

Construire les images

Accéder au docker

Installer les dépendances

Contrôles qualité

Tests unitaires

Tests d'intégration

Style de code

Analyse statique

Tests de mutation (Infection)

Tests de mutation — Infection

Style de code

Analyse statique

Tests unitaires