Arcadia API Kiota Client

Package PHP fournissant le client d'API fortement typé pour l'API Arcadia, généré automatiquement à l'aide de Microsoft Kiota à partir de la spécification OpenAPI 3.0.

Ce package constitue la couche d'infrastructure bas niveau utilisée notamment par le client de haut niveau uwil/arcadia-api-php-client.

---

Prérequis

• PHP : ^8.2 || ^8.3 || ^8.4 || ^8.5
• Extensions PHP : curl, json, mbstring
• Client HTTP PSR-18 / Guzzle : requis pour exécuter les requêtes (ex: guzzlehttp/guzzle: ^7.0)

---

Installation

Via Composer

composer require uwil/arcadia-kiota-open-api-client

Configuration avec le registre GitLab (paquet privé)

Si le paquet est distribué via le registre Composer de GitLab, ajoutez le dépôt dans votre composer.json :

{
  "repositories": [
      {
          "type": "composer",
          "url": "https://lab.s-web.fr/api/v4/group/23/-/packages/composer/packages.json"
      }
  ]
}

Et configurez votre jeton d'accès dans ~/.composer/auth.json ou via la variable d'environnement :

composer config gitlab-token.lab.s-web.fr <VOTRE_TOKEN_GITLAB>

---

Démarrage rapide

Kiota découple la logique de requêtage du moteur HTTP via un RequestAdapter. Voici comment initialiser et utiliser le client avec Guzzle :

use GuzzleHttp\Client as GuzzleHttpClient;
use Microsoft\Kiota\Abstractions\Authentication\AnonymousAuthenticationProvider;
use Microsoft\Kiota\Http\GuzzleRequestAdapter;
use Uwil\ArcadiaKiotaOpenApiClient\ApiClient;

// 1. Configuration du client HTTP de transport
$guzzle = new GuzzleHttpClient([
    'base_uri' => 'https://api.arcadia.example.com',
    'timeout'  => 10.0,
]);

// 2. Création de l'adaptateur de requêtes Kiota
// Note : Si l'API requiert une signature ou des en-têtes d'authentification personnalisés,
// ils peuvent être injectés via des middlewares Guzzle ou un AuthenticationProvider dédié.
$authProvider   = new AnonymousAuthenticationProvider();
$requestAdapter = new GuzzleRequestAdapter($authProvider, $guzzle);
$requestAdapter->setBaseUrl('https://api.arcadia.example.com');

// 3. Instanciation du client d'API généré
$client = new ApiClient($requestAdapter);

// 4. Exemples d'appels d'API (appels asynchrones retournant une Promise)
// Récupérer la liste des marques
$brandList = $client->brands()->get()->wait();
foreach ($brandList->getBrands() as $brand) {
    echo $brand->getCode() . ' - ' . $brand->getLabel() . PHP_EOL;
}

// Récupérer une fiche INCO par son identifiant
$incoItem = $client->incoSheets()->byIncoId('100')->get()->wait();
echo $incoItem->getName() . PHP_EOL;

// Récupérer la composition nutritionnelle d'une fiche INCO
$compoItem = $client->incoSheets()->byIncoId('100')->composition()->get()->wait();
echo 'Énergie kcal : ' . $compoItem->getEnergy()?->getReference()?->getEnergyKcal() . PHP_EOL;

---

Endpoints couverts

Ressource	Méthode Kiota	Endpoint HTTP
Brands	$client->brands()->get()	GET /brands
Brand (Item)	$client->brands()->byBrandCode('...')->get()	GET /brands/{brandCode}
Employees	$client->employees()->get()	GET /employees
Employee (Item)	$client->employees()->byEmployeeId('...')->get()	GET /employees/{employeeId}
Inco Sheets	$client->incoSheets()->get()	GET /inco-sheets
Inco Sheet (Item)	$client->incoSheets()->byIncoId('...')->get()	GET /inco-sheets/{incoId}
Inco Search	$client->incoSheets()->search()->get()	GET /inco-sheets/search
Composition	$client->incoSheets()->byIncoId('...')->composition()->get()	GET /inco-sheets/{incoId}/composition
Health Check	$client->health()->get()	GET /health

---

Régénération du client Kiota (pour les contributeurs)

Lorsque la spécification documentation/openapi.yaml évolue, regénérez le client avec Kiota via Docker :

cd packages/arcadia-api-kiota

docker run --rm \
  -v "${PWD}/client":/app/output \
  -v "${PWD}/documentation/openapi.yaml":/app/openapi.yaml \
  mcr.microsoft.com/openapi/kiota generate \
  --language php \
  -n Uwil\\ArcadiaKiotaOpenApiClient \
  --output /app/output \
  --openapi /app/openapi.yaml \
  --clean-output \
  --type-access-modifier Private

---

Publication et CI/CD

Le déploiement est automatisé via .gitlab-ci.yml. La publication sur le registre Composer GitLab se déclenche à la création d'un tag Git sémantique :

git tag 1.0.0
git push origin 1.0.0

Le pipeline CI exécute alors le job publish qui enregistre automatiquement la nouvelle version du package.

---

Licence

Ce projet est sous licence MIT. Voir le fichier LICENCE.md pour plus de détails.