winzik/docs/ide/fr/api-platform.md

8.6 KiB

API Platform

La fenêtre API Platform (barre d'outils du bas ; Search Everywhere : API Platform : …) apparaît dans un projet dont le composer.json exige api-platform/core (ou un autre paquet api-platform/*). Elle lit l'API dans les sources, sans rien exécuter : les attributs #[ApiResource] des classes des dossiers PSR-4 (entités et DTO, propriétés promues du constructeur comprises), leurs opérations, #[Groups], #[ApiProperty] et #[ApiFilter]. Cinq onglets ; la fenêtre peut prendre tout l'écran (bouton ⤢, Échap la rend). Dans la fenêtre Doctrine, l'éditeur d'entité et le menu du diagramme ont une entrée API Platform… qui ouvre une classe ici.

API Platform n'est pas encore installé ? Cocher API Platform resource (#[ApiResource]) dans la boîte Nouvelle entité affiche un bandeau (API Platform n'est pas installé dans ce projet) avec un bouton Installer API Platform ; Nouveau… > Installer API Platform… aussi. La commande est montrée (composer require api, le pack Flex de Symfony, pour Symfony 6.4+ avec Flex ; api-platform/symfony sans Flex ; api-platform/core:^3.2 / ^2.7 pour un Symfony plus ancien, lu dans composer.lock), lancée par le lanceur de la fenêtre Composer avec sa sortie en direct, et la fenêtre API Platform apparaît sans redémarrer l'IDE. Refusé : l'attribut est quand même écrit, avec un avertissement (la classe est indéfinie tant que le paquet n'est pas installé). Toute autre classe indéfinie (Undefined class 'X\Y') a la correction rapide Installer le paquet manquant… (candidats : une table intégrée des espaces de noms courants, puis Packagist).

Les options d'une ressource et ses opérations

Chaque changement est calculé ici et montré en diff d'abord ; rien n'est écrit avant Appliquer. Seuls les arguments touchés changent : l'attribut est modifié argument par argument (positions de php-parser), tout le reste garde ses octets exacts, le style de la liste (une ligne ou un argument par ligne) est suivi, et les lignes use sont ajoutées. Une valeur que le code tient pour une expression (security: self::RULE, 'groups' => [Book::READ]) est affichée telle quelle et jamais réécrite.

Le diff avant l'écriture

Ressources

La liste de gauche contient les entités et DTO du projet (badge API si la classe a #[ApiResource] ; filtre par classe ou nom court). Pour la classe choisie :

  • #[ApiResource] oui / non : L'exposer avec #[ApiResource] ajoute l'attribut (et son use), Retirer #[ApiResource] l'enlève. Une classe à plusieurs #[ApiResource] (une sous-ressource a son propre uriTemplate + uriVariables) montre une pastille par attribut ; Sous-ressource en ajoute un.
  • Général : nom court, modèle d'URI, variables d'URI (new Link(fromClass:, fromProperty:, toProperty:)).
  • Sérialisation et validation : groupes de normalisation, de dénormalisation et de validation (pastilles ; les autres clés du contexte, enable_max_depth… restent).
  • Sécurité : security, securityPostDenormalize, securityMessage.
  • Pagination : activée (défaut / oui / non), éléments par page, contrôle du client, maximum par page.
  • Formats et ordre : jsonld, json, jsonapi, hal, xml, csv, html ; l'ordre par défaut (['title' => 'ASC']).
  • State : provider, processor, input, output (une classe, ou false).
  • Opérations : Get, GetCollection, Post, Put, Patch, Delete, chacune avec sa route (méthode et chemin) et ses options propres (nom, uriTemplate, controller, sécurité, groupes, pagination, provider / processor / input / output) : ajout, suppression, changement de type. Quand le code n'en liste aucune, les opérations par défaut d'API Platform sont montrées (Get, GetCollection, Post, Patch, Delete ; Put aussi avant API Platform 4) ; Les rendre explicites pour les modifier écrit la liste.

Propriétés

La grille des propriétés

Une grille, une ligne par propriété (une clé marque l'identifiant ; le type Doctrine ou la relation est indiqué). Colonnes de groupes : les groupes de sérialisation des contextes de la ressource et des propriétés ; chaque case est l'attribut #[Groups([...])] (créé, modifié ou retiré). En en-tête, R et W disent si le groupe est un groupe de lecture (normalizationContext de la ressource) et / ou d'écriture (denormalizationContext) ; les basculer modifie la ressource dans le même diff, et + Groupe ajoute une colonne. Puis : Lisible, Modifiable, Identifiant, Description, Exemple (#[ApiProperty], retiré s'il ne lui reste aucun argument) et Filtres : SearchFilter (stratégie exact, partial, start, end, word_start), OrderFilter, RangeFilter, DateFilter, BooleanFilter, ExistsFilter, NumericFilter en attributs #[ApiFilter(...)] (un filtre déjà là garde ses autres arguments). Les filtres déclarés sur la classe sont listés sous la grille.

State

Les classes qui implémentent ProviderInterface / ProcessorInterface, avec leurs usages. Nouveau provider… / Nouveau processor… écrivent une classe depuis un modèle (src/State/), éventuellement en décorant ceux de Doctrine (providers de collection / d'élément, processor de persistance, injectés avec #[Autowire]), et la branchent à la ressource dans le même diff (processor: BookProcessor::class). Brancher… connecte une classe existante.

Routes

Toutes les routes, déduites du code (méthode, chemin avec le préfixe de config/routes/api_platform.yaml, ressource, opération, sécurité, nom) ; un clic ouvre la ressource. Comparer avec debug:router lance debug:router par le lanceur de la fenêtre Console et marque chaque route ✓ / ✗, et liste les routes d'API de la console que le code n'explique pas. Export OpenAPI montre api:openapi:export.

Requêtes

L'état de chaque fichier de requête

La collection générée dans le client HTTP

Générer pour toutes les ressources (ou pour une) fabrique, pour chaque ressource, une collection du client HTTP http-requests/<Ressource>/ :

  • un fichier .http par opération (list, get, create, replace, update, delete, <personnalisée> ; les sous-ressources dans un dossier sub-…) : URL sous {{baseUrl}}, la méthode, Accept et Content-Type (application/ld+json, ou le premier des formats ; application/merge-patch+json pour PATCH), un corps d'exemple construit avec les propriétés que l'opération écrit (groupes de dénormalisation, #[ApiProperty(writable: false)] exclu, la classe input s'il y en a une) avec des valeurs d'exemple selon le type (#[ApiProperty(example:)], le premier cas d'un enum, une IRI pour une relation), les filtres en paramètres de requête commentés (# ?title=…, # ?order[title]=asc, # ?pages[gte]=1, # ?page=2), un test de statut, et un script qui garde le nouvel id ({{bookId}} utilisé par les autres requêtes) ;
  • une nouvelle collection reçoit l'environnement (baseUrl, les ids, le login) et, avec lexik/jwt-authentication-bundle, une requête de login JWT (lue dans security.yaml) que l'authentification de la collection utilise.

La régénération suit la classe, avec une règle : une requête que quelqu'un a modifiée n'est jamais écrasée. Le .apiplatform.json de la collection garde l'empreinte de ce que l'outil a écrit. Un fichier encore identique est réécrit (ou supprimé si l'opération a disparu) ; un fichier différent, ou que l'outil n'a jamais écrit, reste tel quel et la nouvelle version est écrite à côté sous nom.theirs.http (seulement s'il y a du nouveau). La fenêtre montre l'état de chaque fichier (nouveau, sera rafraîchi, à jour, le vôtre conservé, supprimé) et le diff avant l'écriture.

Tests

ide/tests/ApiPlatformTest.php : les attributs lus sous plusieurs formes, le texte exact de chaque changement (tests/fixtures/api-platform-expected/), la grille des propriétés, les classes State, les requêtes et les règles de régénération. games/ide/tools/api-platform-check.sh <une copie d'un projet Symfony avec api-platform/core> est le contrôle réel : une entité faite par le backend de la fenêtre Doctrine, #[ApiResource] modifié, debug:router, et les requêtes générées exécutées par le client HTTP contre php -S. games/ide/tools/ui-api-platform-check.sh prend les captures de cette page.