SDK PHP officiel d'Upsun

Contexte

L'API d'Upsun est riche (organisations, projets, environnements, variables, déploiements…) mais l'appeler depuis PHP voulait dire écrire soi-même les requêtes HTTP, l'authentification et les modèles. Il fallait un SDK officiel, complet, et qui reste à jour sans effort quand l'API évolue.

Ce que j'ai construit

À partir du squelette de départ posé par un collègue de l'équipe Advocacy, j'ai réalisé l'essentiel du SDK : la couverture complète de l'API, les façades, les tests et la publication sur Packagist. L'architecture tient en deux couches :

• Une couche générée avec OpenAPI Generator à partir de la spécification OpenAPI officielle, servie par Meta-Upsun : un modèle par schéma, une classe par groupe d'endpoints. Elle couvre 100 % de l'API publique.
• Une couche « Tasks » écrite à la main, l'interface publique : $client->projects->create(...), $client->organizations->listProjects(...), avec arguments nommés, types stricts et propriétés readonly. Les développeurs n'ont jamais à manipuler les modèles générés.

Autour :

• Un pré-traitement de la spécification en PHP avant génération : les gabarits Mustache ne savent faire que des tests simples, donc les transformations (ajout de champs x-*, corrections) se font en amont, dans du code testable.
• Une synchronisation quotidienne : un workflow GitHub compare la spécification publiée à la copie locale et ouvre une pull request en cas de différence.
• L'alignement avec le SDK Node.js : mêmes noms de méthodes et mêmes signatures, contrôlés par un outil de vérification que j'ai écrit et qui signale toute divergence entre les deux SDK.
• 476 tests PHPUnit (plus de 3 500 assertions) et une PHPDoc complète pour l'autocomplétion dans l'IDE.
• Distribution sur Packagist : composer require upsun/upsun-sdk-php. Code source sur GitHub.
• Une documentation de l'architecture et du code, interrogeable, sur DeepWiki.

Défis techniques

• Une spécification réelle n'est jamais parfaite : schémas incomplets, types ambigus. Le pré-traitement corrige sans modifier la source officielle, et chaque correction est versionnée.
• Séparer le généré du maintenu : la couche Tasks protège les utilisateurs des changements du code généré. Une évolution de l'API ne casse pas leur code.

Résultats

• Un SDK officiel, open source, publié sur Packagist et documenté.
• Des signatures cohérentes avec le SDK Node.js, et une approche prévue pour Python et Go.