Download the PHP package sociolink/api-resource-bundle without Composer

SocioLink\ApiResourceBundle

Génère les ressources API Platform (DTOs, State Processors/Providers, paramètres de filtrage #[QueryParameter]) à partir des entités Doctrine, via une commande CLI interactive.

Outil de développement. Le code qu'il génère ne référence jamais le bundle — il ne dépend que d'API Platform, de Symfony et de Doctrine — et fonctionne donc en production sans lui.

Licence. Ce dépôt est public afin d'être distribué via Packagist, mais il n'est pas open source : aucun droit d'utilisation, de modification ou de redistribution n'est accordé en dehors des projets explicitement autorisés par l'auteur. Voir LICENSE.

Prérequis

Le bundle dépend des composants d'API Platform, jamais du paquet monolithique api-platform/core. Il s'installe donc sans rien retirer, que le projet utilise les composants (api-platform/symfony, installation actuelle) ou api-platform/core (qui remplace ces composants). Les tests générés par --with-tests utilisent en plus api-platform/test (ApiPlatform\Test\ApiTestCase) :

Le bundle reconnaît sans configuration le type Doctrine phone_number d'odolbeau/phone-number-bundle (^4.2, voir Types Doctrine personnalisés). Ce bundle n'est pas une dépendance obligatoire : seuls les projets qui stockent des numéros de téléphone l'installent, en require, car leurs entités en dépendent aussi en production.

Installation

Versions

Le bundle suit le versionnage sémantique ; chaque version est un tag Git vX.Y.Z, publié sur Packagist, et décrite dans le CHANGELOG. Préférez la contrainte ^1.0 à dev-main : composer update n'apporte alors que des versions publiées et compatibles.

Le contrat public, dont toute rupture impose une version majeure, comprend : le nom et les options de la commande, les clés de configuration sociolink_api_resource.*, et la forme du code généré (noms et emplacements des fichiers, shortName et URIs des ressources). Les classes internes (@internal) n'en font pas partie.

Avec Symfony Flex

Dans un projet utilisant Symfony Flex (tout projet créé avec symfony new ou symfony/skeleton), le bundle est enregistré automatiquement. Le paquet étant installé avec --dev, Flex le réserve aux environnements dev et test.

Par défaut, Flex applique une recette auto-générée, qui enregistre le bundle sans créer de fichier de configuration (toutes les clés sont optionnelles, voir Configuration) :

Le dépôt publie aussi sa propre recette (dossier flex/, compilé depuis recipe/), qui crée en plus config/packages/sociolink_api_resource.yaml, toutes les clés en commentaire avec leur valeur par défaut. Pour l'utiliser, déclarez ce dépôt de recettes dans le composer.json du projet, avant d'installer le bundle :

flex://defaults conserve les recettes officielles de Symfony pour les autres paquets. Composer affiche alors From github.com/SocioLink/ApiResourceBundle:main.

Sans Flex

Ajoutez le bundle à la main dans config/bundles.php :

Utilisation

Sans argument :

• dans un terminal, le menu numéroté s'affiche (voir ci-dessous) ;
• sans terminal (CI, --no-interaction), la commande échoue avec un message explicite — jamais de traitement implicite de toutes les entités.

Menu interactif

Les entités sont regroupées par namespace (ordre alphabétique), numérotées en continu, choix unique ; « All » (dernier numéro) traite toutes les entités existantes.

Options

Destructrices

Mutuellement exclusives (une seule à la fois)

Indépendantes

Sans --with-mercure, aucune directive mercure n'est injectée.

La commande se termine en échec (code 1) si une entité n'a pas pu être traitée ; les autres entités sont tout de même générées.

Artefacts générés

Filtres générés

Les filtres sont déclarés en tant que paramètres parameters: [ ... ] directement sur l'attribut #[ApiResource] (#[ApiFilter], déprécié depuis API Platform 4.4, n'est jamais généré). Grâce à ce positionnement sur la ressource, API Platform cascade automatiquement ces filtres à la fois sur les routes de collection REST (GetCollection) et sur les collections GraphQL (QueryCollection) :

Exclus de tout filtre : id, text, json, array, simple_array, blob, binary, dateinterval, ainsi que les champs listés dans filters.excluded_fields.

Une chaîne est recherchée par sous-chaîne (LOWER(champ) LIKE LOWER('%valeur%'), avec % et _ échappés). Une énumération (colonne string avec enumType) reste en égalité stricte, car ses valeurs sont fermées. Un type personnalisé (phone_number…) aussi, car sa valeur en base est une conversion de l'objet PHP. Sur une grande table, une recherche LIKE '%…%' ne peut pas utiliser d'index B-tree : excluez au besoin le champ (filters.excluded_fields).

Configuration

Toutes les clés sont optionnelles ; les valeurs par défaut conviennent à une application Symfony standard (App\ dans src/). Fichier config/packages/dev/sociolink_api_resource.yaml :

Pour surcharger un gabarit, copiez-le depuis templates/ du bundle dans templates_directory : les gabarits absents du dossier de surcharge restent ceux du bundle.

Types Doctrine personnalisés

Un type Doctrine standard est converti vers son type PHP (string, int, DateTimeImmutable, Uuid…). Un type inconnu est traité comme une chaîne, et la commande le signale par un avertissement. Or si Doctrine hydrate ce type en objet, un DTO typé string fait échouer le setter de l'entité (TypeError) : déclarez alors la classe hydratée dans custom_types, et le DTO sera typé et importé en conséquence.

phone_number (odolbeau/phone-number-bundle) est prédéfini : les DTOs typent le champ en libphonenumber\PhoneNumber. Le normaliseur de ce bundle (activé dès que le Serializer de Symfony est installé) convertit la chaîne JSON reçue ("+33612345678") en objet, puis le numéro est ressérialisé au format E.164. Les tests générés utilisent +33612345678 comme valeur d'exemple. Une entrée de custom_types peut redéfinir un type prédéfini.

Pour un autre type objet, le projet doit fournir un dénormaliseur (chaîne JSON → objet), faute de quoi API Platform rejette la requête.

Structure des fichiers générés

Qualité

La suite comprend un test de bout en bout (tests/Functional) : le bundle est enregistré dans un noyau Symfony avec un EntityManager Doctrine réel, la commande est exécutée dans chaque mode, puis chaque classe générée est chargée et chaque #[ApiResource] injecté est instancié avec API Platform. SOCIOLINK_E2E_KEEP=1 composer test conserve le projet généré pour inspection.

Les tests de tests/Recipe vérifient aussi que le fichier de configuration de la recette Flex reprend exactement les valeurs par défaut, et que flex/ correspond à la recompilation de recipe/ (php recipe/build.php).

CI GitHub Actions (.github/workflows/ci.yml) : PHP 8.5 × Symfony 7.4/8.0/8.1 avec les dépendances les plus récentes, plus une tâche avec les versions minimales de composer.json (--prefer-lowest).

Portage depuis la commande de projet

Ce bundle remplace la commande generate:resource qui vivait auparavant dans un projet applicatif (App\Command\GenerateResource). Changements de comportement à connaître lors du portage :

• toutes les conventions codées en dur (App\, src/, ROLE_ADMIN, champs système) sont désormais dans GeneratorConfig, configurables via sociolink_api_resource.* ;
• la directive mercure n'est plus injectée par défaut — utilisez --with-mercure pour retrouver l'ancien comportement (mercure: ['private' => true]) ;
• les tests générés (--with-tests) vivent dans tests/Functional/ et non plus src/Tests/ ;
• sans argument, un terminal affiche désormais un menu à choix unique au lieu de traiter toutes les entités ;
• --reinit ne supprime plus les dossiers racines DTO/ et State/, seulement ceux des entités traitées.

Depuis une version antérieure du bundle (BlackSheep\Symfony\ApiResourceBundle)

• espace de noms : SocioLink\ApiResourceBundle (à mettre à jour dans config/bundles.php) ;
• racine de configuration : sociolink_api_resource (au lieu de black_sheep_api_resource) ;
• alias de commande : sociolink:api-resource:generate (au lieu de black-sheep:api-resource:generate).

Licence

Ce projet est distribué sous licence propriétaire (voir LICENSE). Le dépôt est public afin de permettre sa distribution via Packagist, mais aucun droit d'utilisation, de modification ou de redistribution n'est accordé en dehors des projets explicitement autorisés par l'auteur.

Auteur

Xavier Kongolo