JSON streamer pour les grandes collections

Le serializer Symfony par défaut construit la réponse complète en mémoire avant de l’écrire dans la sortie. Pour une collection de 10 000 éléments, cela signifie allouer un tableau PHP, le sérialiser en string, et garder les deux en mémoire jusqu’au flush de la réponse. À grande échelle, c’est la source des erreurs OOM qui forcent à ajouter de la pagination partout.

La 4.2 ajoute un encodeur JSON en streaming qui écrit la réponse de façon incrémentale :

api_platform:
    serializer:
        enable_json_streamer: true

Avec le streaming activé, la réponse est écrite directement dans le buffer de sortie au fur et à mesure que chaque élément est sérialisé. L’utilisation mémoire reste approximativement constante quelle que soit la taille de la collection. La contrepartie : on ne peut pas définir de headers de réponse après le début du streaming, et le code de statut HTTP doit être validé avant que le premier octet soit écrit.

ObjectMapper remplace le câblage DTO manuel

La 3.1 avait introduit stateOptions avec DoctrineOrmOptions pour séparer la ressource API de l’entité Doctrine. Le provider recevait des objets entité et le serializer les mappait sur le DTO. Ça fonctionnait, mais le mapping était implicite — le serializer utilisait les noms de propriétés pour faire correspondre les champs, et tout ce qui ne correspondait pas était soit ignoré soit causait une erreur de normalisation.

La 4.2 introduit ObjectMapper, une couche de mapping déclarative entre entités et DTOs :

use Symfony\Component\ObjectMapper\Attribute\Map;

#[Map(source: BookEntity::class)]
class BookDto
{
    public string $title;
    public string $authorName;
}

L’attribut #[Map] indique à ObjectMapper que BookDto peut être peuplé depuis BookEntity. Les noms de champs sont mis en correspondance par convention ; les inadéquations sont déclarées explicitement au niveau de chaque propriété :

use Symfony\Component\ObjectMapper\Attribute\Map;

#[Map(source: BookEntity::class)]
class BookDto
{
    #[Map(source: 'author.fullName')]
    public string $authorName;
}

La notation pointée traverse les objets imbriqués. Le mapping s’exécute avant la sérialisation et remplace le comportement implicite de correspondance de propriétés du serializer. Les champs non mappés lèvent une erreur au moment de la configuration, pas à l’exécution.

ObjectMapper fonctionne avec stateOptions :

use ApiPlatform\Doctrine\Orm\State\Options;
use ApiPlatform\Metadata\ApiResource;
use ApiPlatform\Metadata\GetCollection;
use Symfony\Component\ObjectMapper\Attribute\Map;

#[ApiResource(
    operations: [
        new GetCollection(
            stateOptions: new Options(entityClass: BookEntity::class),
        ),
    ]
)]
#[Map(source: BookEntity::class)]
class BookDto {}

Le provider récupère les objets BookEntity depuis Doctrine. ObjectMapper les convertit en instances BookDto. Le serializer écrit le DTO. Trois étapes distinctes, chacune avec un contrat clair.

Intégration TypeInfo dans toute la pile

Symfony 7.1 a introduit le composant TypeInfo , une couche unifiée d’introspection des types qui comprend les types union, intersection, les collections génériques et les types nullable à travers la reflection, PHPDoc et la syntaxe PHP 8.x.

La 4.2 remplace la résolution de types interne d’API Platform par TypeInfo. Cela affecte la génération de schémas de filtres, l’inférence de schéma OpenAPI, et la coercition de types du serializer. Le bénéfice visible est que les types qui généraient auparavant des schémas OpenAPI incorrects ou manquants — Collection<int, Book>, list<string>, types intersection — produisent maintenant des schémas précis sans annotations @ApiProperty manuelles.

Autoconfigure #[ApiResource]

Avant la 4.2, ajouter #[ApiResource] à une classe suffisait pour qu’Hugo la découvre uniquement si la classe était dans un chemin scanné par le chargeur de ressources d’API Platform. En dehors de ce chemin, une configuration de service explicite était nécessaire.

La 4.2 se branche sur le système d’autoconfigure de Symfony. Toute classe taguée avec #[ApiResource] est automatiquement enregistrée comme ressource indépendamment de son emplacement, tant qu’elle est dans un répertoire couvert par le scan de composants de Symfony. Aucune entrée dans config/services.yaml nécessaire.

Pour Laravel, l’équivalent utilise l’autoloading du service provider de Laravel — les modèles Eloquent avec #[ApiResource] sont récupérés automatiquement sans enregistrement manuel.

Doctrine ExistsFilter

L’ExistsFilter contraint une collection selon qu’une relation ou un champ nullable est défini :

#[ApiFilter(ExistsFilter::class, properties: ['publishedAt'])]
class Book {}

GET /books?exists[publishedAt]=true retourne les livres où publishedAt n’est pas null. exists[publishedAt]=false retourne les livres où il l’est.

Validation stricte des paramètres de requête

La 3.3 avait introduit la validation des paramètres de requête en opt-in. La 3.4 avait déprécié le comportement permissif. La 4.1 la formalise avec une propriété native strictQueryParameterValidation sur les ressources et opérations : quand elle est à true, les paramètres de requête inconnus renvoient 400.

use ApiPlatform\Metadata\GetCollection;
use ApiPlatform\Metadata\QueryParameter;

#[GetCollection(
    strictQueryParameterValidation: true,
    parameters: [
        new QueryParameter(key: 'utm_source', required: false, schema: ['type' => 'string']),
        new QueryParameter(key: 'feature_flag', required: false, schema: ['type' => 'string']),
    ]
)]
class Book {}

Les paramètres déclarés passent ; les paramètres non déclarés sont rejetés. Pour désactiver la validation stricte sur une opération spécifique quand elle est activée au niveau de la ressource, passer strictQueryParameterValidation: false sur cette opération.

x-apiplatform-tag pour OpenAPI multi-spec

Les grandes APIs ont souvent besoin de plusieurs specs OpenAPI : une par équipe, une par version d’API, une interne et une publique. Avant la 4.1, la spec générée était un seul document, et la diviser nécessitait un post-traitement ou des instances API Platform séparées.

La 4.1 ajoute une extension vendor x-apiplatform-tag (sans s final). On tague les opérations avec des noms de groupes logiques via les extensionProperties d’un objet Operation OpenAPI, puis on demande la spec filtrée sur un ou plusieurs groupes :

use ApiPlatform\Metadata\GetCollection;
use ApiPlatform\OpenApi\Factory\OpenApiFactory;
use ApiPlatform\OpenApi\Model\Operation;

#[GetCollection(
    openapi: new Operation(
        extensionProperties: [OpenApiFactory::API_PLATFORM_TAG => ['public', 'v2']]
    )
)]
class Book {}

Demander /api/docs.json?filter_tags[]=public retourne uniquement les opérations taguées public. La spec complète reste disponible sans filtre. Les groupes n’affectent pas le comportement réel de l’API — c’est uniquement une préoccupation de couche documentation.

Cela rend faisable de maintenir une configuration API Platform unique tout en servant différentes vues de spec à différents consommateurs : un Swagger UI public, un portail partenaire, et un outil interne qui expose les endpoints d’administration.

Authentification HTTP dans Swagger UI

Avant la 4.1, le Swagger UI fourni avec API Platform supportait l’authentification par token Bearer via son dialogue “Authorize”. L’authentification par clé API et HTTP Basic n’étaient pas câblées.

La 4.1 ajoute le support de plusieurs schémas de sécurité dans le document OpenAPI généré. Les schémas de sécurité sont ajoutés en décorant l’OpenApiFactory et en modifiant l’objet components.securitySchemes de la spec. Chaque schéma déclaré apparaît ensuite dans le dialogue “Authorize” de Swagger UI et est appliqué aux requêtes faites depuis l’UI. C’est une amélioration de la documentation et de l’expérience développeur — la logique d’authentification réelle dans votre application n’est pas affectée.

Limites de profondeur et complexité des requêtes GraphQL

La structure de requête récursive de GraphQL rend triviale la construction d’une requête petite en octets mais énorme en coût d’exécution. Sans limites, une requête imbriquée sur quatre niveaux à travers une relation many-to-many peut frapper la base de données des centaines de fois.

La 4.1 ajoute des limites configurables de profondeur et complexité :

api_platform:
    graphql:
        max_query_depth: 10
        max_query_complexity: 100

max_query_depth est le niveau d’imbrication maximum. max_query_complexity assigne un coût à chaque champ et rejette les requêtes dont le coût total dépasse le seuil. Les requêtes qui dépassent l’une ou l’autre limite sont rejetées avant exécution avec une réponse 400.

Il n’y a pas de valeur universellement correcte pour ces limites — elles dépendent de la forme de votre schéma et des patterns de requête attendus. Les valeurs par défaut sont intentionnellement permissives pour éviter de casser des APIs existantes lors de la mise à jour. Les resserrer est un choix de configuration délibéré.

Formats de sortie au niveau opération

La 4.0 et les versions antérieures configuraient les types de contenu acceptés et retournés au niveau de l’API. La 4.1 permet de les restreindre par opération :

use ApiPlatform\Metadata\GetCollection;

#[GetCollection(
    outputFormats: ['jsonld' => ['application/ld+json']],
    inputFormats: ['json' => ['application/json']],
)]
class Book {}

Les opérations qui ne spécifient pas de formats héritent de la configuration au niveau de l’API. C’est utile pour les endpoints qui doivent retourner un format spécifique (une export CSV, un flux binaire) sans changer les défauts pour le reste de l’API.

Laravel comme cible de première classe

Depuis sa première release, API Platform était construit sur Symfony. La couche HTTP, les métadonnées, le serializer et le bridge Doctrine supposaient tous le container de Symfony, l’event dispatcher et le cycle de vie des requêtes. Les utilisateurs Laravel pouvaient faire tourner API Platform via un adaptateur léger, mais les filtres, la sécurité et l’intégration Doctrine ne fonctionnaient pas avec Eloquent.

La 4.0 livre un bridge Laravel dédié. Il mappe la couche d’état d’API Platform sur le cycle de vie des requêtes de Laravel, s’intègre directement avec les modèles Eloquent, et se branche sur le système d’autorisation de Laravel :

use ApiPlatform\Metadata\ApiResource;
use ApiPlatform\Metadata\Get;
use ApiPlatform\Metadata\GetCollection;
use Illuminate\Database\Eloquent\Model;

#[ApiResource(
    operations: [new GetCollection(), new Get()]
)]
class Book extends Model
{
    protected $fillable = ['title', 'author'];
}

L’autorisation utilise les policies et gates de Laravel plutôt que les security voters de Symfony. Les opérations exposent un paramètre policy dédié qui correspond à un nom de méthode de policy :

#[Get(policy: 'view')]
class Book extends Model {}

API Platform mappe la valeur de policy vers Gate::allows() de Laravel avec l’instance du modèle. Les policies peuvent aussi être auto-détectées : si un modèle a une classe de policy enregistrée, API Platform infère la bonne méthode (view, viewAny, create, update, delete) selon le type d’opération. Les filtres pour les collections Eloquent couvrent le même périmètre que leurs homologues Doctrine : PartialSearchFilter, EqualsFilter, RangeFilter, OrderFilter, DateFilter, et des variantes de recherche (StartSearchFilter, EndSearchFilter). La pagination, le tri et la validation fonctionnent via les mécanismes natifs de Laravel.

Ce n’est pas un shim de compatibilité. Le bridge Laravel est maintenu aux côtés du bridge Symfony et est couvert par la même suite de tests. Les projets utilisant l’un ou l’autre framework ont la même API de définition des ressources.

PUT supprimé des opérations par défaut

Depuis API Platform 1.0, #[ApiResource] sans tableau operations explicite générait des opérations CRUD incluant PUT. Le handler PUT mettait à jour les ressources existantes et, depuis la 3.1, pouvait aussi les créer via allowCreate: true.

La 4.0 supprime PUT de l’ensemble par défaut. #[ApiResource] génère maintenant GET, POST, PATCH et DELETE. Pour utiliser PUT, il faut le déclarer explicitement :

use ApiPlatform\Metadata\ApiResource;
use ApiPlatform\Metadata\Put;

#[ApiResource(
    operations: [
        // ... autres opérations
        new Put(),
    ]
)]
class Book {}

La motivation est la clarté sémantique. PATCH remplace PUT pour la plupart des cas d’usage de mise à jour partielle. La sémantique de PUT — remplacer la représentation entière de la ressource — est rarement ce qu’une API implémente réellement, mais le défaut le faisait apparaître dans toutes les APIs à moins de l’enlever activement. Rendre PUT opt-in aligne les défauts sur la façon dont la sémantique HTTP est réellement utilisée en pratique.

PHP 8.2 minimum

La 4.0 abandonne PHP 8.0 et 8.1. PHP 8.2 est le nouveau minimum. La syntaxe de classe readonly, AllowDynamicProperties et les types DNF¹ introduits en 8.2 sont disponibles dans toute la codebase. Aucune fonctionnalité spécifique de 8.2 n’est structurante pour la 4.0 — le bump de version concerne principalement l’abandon du fardeau de maintenance plus ancien.

Symfony 6.4+ et Doctrine ORM 2.17+ minimum

Côté Symfony, la 4.0 requiert Symfony 6.4 ou 7.x et Doctrine ORM 2.17 ou 3.x. Les deux étaient déjà supportés en 3.4. La migration de la 3.4 vers la 4.0 sur la piste Symfony est : résoudre les dépréciations 3.4, vérifier qu’on est sur Symfony 6.4+ et ORM 2.17+, puis mettre à jour. Aucun travail de migration supplémentaire n’est nécessaire si c’est déjà en place.

Ce que la 4.0 n’est pas

La 4.0 n’est pas une nouvelle architecture. Les state providers, processors et le modèle de métadonnées de ressources de la 3.0 sont inchangés. Le bridge Laravel ajoute un nouveau contexte d’exécution mais ne change pas la façon dont les ressources ou les opérations sont déclarées. La séparation est intentionnelle : si la 3.0 était le “quoi”, la 4.0 est le “où”.

BackedEnum comme ressources API

Depuis PHP 8.1, les classes BackedEnum ont un ensemble fixe de cas avec des valeurs de support string ou integer. API Platform 3.4 permet de mettre #[ApiResource] directement sur un BackedEnum :

use ApiPlatform\Metadata\ApiResource;
use ApiPlatform\Metadata\GetCollection;

#[ApiResource(
    operations: [new GetCollection()]
)]
enum BookStatus: string
{
    case Draft = 'draft';
    case Published = 'published';
    case Archived = 'archived';
}

Un endpoint GET /book_statuses retourne la liste des cas. Chaque cas est sérialisé avec son nom et sa valeur. L’endpoint est en lecture seule — les enums sont immuables par nature.

C’est surtout utile pour les consommateurs frontend qui veulent une liste lisible par machine des valeurs valides sans les coder en dur. L’alternative était un contrôleur personnalisé ou une ressource DTO dédiée listant manuellement les valeurs de l’enum.

BackedEnumFilter

Le compagnon des ressources enum est BackedEnumFilter, un nouveau filtre pour les collections Doctrine qui contraint une requête par une propriété BackedEnum :

use ApiPlatform\Doctrine\Orm\Filter\BackedEnumFilter;
use ApiPlatform\Metadata\ApiFilter;
use ApiPlatform\Metadata\ApiResource;

#[ApiResource]
#[ApiFilter(BackedEnumFilter::class, properties: ['status'])]
class Book
{
    public BookStatus $status;
}

GET /books?status=published filtre la collection aux livres où status est égal à BookStatus::Published. Les valeurs d’enum invalides retournent une réponse 400. Avant ce filtre, on devait soit écrire un filtre personnalisé, soit utiliser SearchFilter et valider la valeur manuellement.

Expressions de sécurité sur les paramètres

La 3.3 avait ajouté la sécurité aux liens et aux propriétés. La 3.4 étend cela aux paramètres de requête. Un paramètre peut déclarer une expression de sécurité qui contrôle s’il est accepté :

use ApiPlatform\Metadata\GetCollection;
use ApiPlatform\Metadata\QueryParameter;

#[GetCollection(
    parameters: [
        new QueryParameter(
            key: 'includeDeleted',
            security: "is_granted('ROLE_ADMIN')"
        ),
    ]
)]
class Book {}

Quand l’expression de sécurité est false, le paramètre est rejeté avec un 403, pas silencieusement ignoré. C’est plus explicite que vérifier le rôle de l’utilisateur dans le provider après avoir reçu le paramètre.

Support DBAL 4 ajouté

La 3.4 ajoute le support de Doctrine DBAL 4, qui apporte des changements au système de types qui affectent la façon dont les types personnalisés et le SQL spécifique à la plateforme fonctionnent. Les filtres Doctrine Orm et les extensions de requête dans API Platform ont été mis à jour pour fonctionner avec la nouvelle API de types DBAL 4.

DBAL 3 (^3.4.0) et DBAL 4 sont supportés simultanément en 3.4. C’est la release à adopter pour migrer vers DBAL 4 tout en restant sur une branche stable API Platform 3.x.

Validateur de paramètres de requête déprécié

La 3.3 avait ajouté le validateur strict de paramètres de requête en opt-in. La 3.4 déprécie l’ancien comportement (paramètres inconnus silencieusement ignorés) en préparation pour rendre la validation stricte la valeur par défaut en 4.0. Les projets qui s’appuient sur des paramètres de requête pass-through ont une release de plus pour les déclarer explicitement.

Dernier arrêt avant la 4.0

La 3.4 est la dernière release 3.x avec de nouvelles fonctionnalités. Tout ce qui était déprécié d’ici la 3.4 disparaît en 4.0. Le chemin de migration de la 3.4 vers la 4.0 est intentionnellement court : résoudre les dépréciations, puis mettre à jour.

Configuration déclarative des headers

Avant la 3.3, définir des headers de réponse personnalisés nécessitait soit un processor personnalisé qui modifiait l’objet réponse, soit un event listener Symfony sur kernel.response. Les deux approches fonctionnaient mais vivaient en dehors de la définition de la ressource.

La 3.3 ajoute un paramètre parameters aux métadonnées d’opération :

use ApiPlatform\Metadata\Get;
use ApiPlatform\Metadata\HeaderParameter;

#[Get(
    parameters: [
        'X-Custom-Header' => new HeaderParameter(description: 'A custom header'),
    ]
)]

Pour les headers qui varient par réponse (comme Cache-Control avec un max-age calculé), le processor peut encore les définir directement sur l’objet réponse. Le paramètre parameters sert principalement à documenter les headers attendus dans la spec OpenAPI et pour les valeurs de headers statiques.

Sécurité des liens sur les sous-ressources

Quand une ressource expose des liens vers des ressources liées, ces liens apparaissent dans la sortie sérialisée indépendamment du fait que l’utilisateur courant puisse accéder à la ressource liée. Cela crée un problème de divulgation : un utilisateur qui peut lire un livre mais pas le profil de son auteur voit quand même l’URI de l’auteur dans la réponse.

La 3.3 ajoute des expressions de sécurité au descripteur Link :

use ApiPlatform\Metadata\ApiResource;
use ApiPlatform\Metadata\Get;
use ApiPlatform\Metadata\Link;

#[ApiResource]
#[Get]
class Book
{
    #[Link(
        toClass: Author::class,
        security: "is_granted('ROLE_ADMIN')"
    )]
    public Author $author;
}

Le lien est omis de la réponse quand l’expression de sécurité évalue à false. La ressource liée elle-même n’est pas affectée — seulement le fait que la réponse courante inclue la référence à elle.

ApiProperty::security

Le même mécanisme d’expression de sécurité est disponible au niveau propriété via ApiProperty::security. Cela permet de cacher des champs individuels selon l’utilisateur courant sans écrire un normalizer personnalisé :

use ApiPlatform\Metadata\ApiProperty;

class Book
{
    #[ApiProperty(security: "is_granted('ROLE_ADMIN')")]
    public string $internalNote;
}

La propriété est exclue de la sérialisation quand l’expression est false. C’est plus propre qu’un normalizer pour le cas courant de champs conditionnels par rôle.

Webhooks OpenAPI

OpenAPI 3.1 supporte les webhooks — des appels HTTP sortants que votre API fait à des listeners enregistrés — dans le document spec lui-même. Avant la 3.3, il n’y avait pas de moyen de les documenter dans la spec générée par API Platform.

La 3.3 ajoute une classe Webhook à passer au paramètre openapi d’une opération. On déclare une classe PHP dédiée avec #[ApiResource] et on utilise Webhook sur chaque opération pour décrire la forme de l’appel sortant :

use ApiPlatform\Metadata\ApiResource;
use ApiPlatform\Metadata\Post;
use ApiPlatform\OpenApi\Attributes\Webhook;
use ApiPlatform\OpenApi\Model\Operation;
use ApiPlatform\OpenApi\Model\PathItem;

#[ApiResource(
    operations: [
        new Post(
            openapi: new Webhook(
                name: 'bookCreated',
                pathItem: new PathItem(
                    post: new Operation(summary: 'Un livre a été créé'),
                ),
            )
        ),
    ]
)]
class BookWebhook {}

Les définitions de webhooks apparaissent dans la spec générée sous la clé webhooks aux côtés des paths réguliers. Swagger UI les affiche dans une section séparée.

Deep linking dans Swagger UI

Swagger UI supporte le deep linking — des URLs mémorisables qui ouvrent directement sur une opération spécifique dans l’interface. Avant la 3.3, l’intégration API Platform n’activait pas cela. La 3.3 active l’option deepLinking de Swagger UI, configurable via swagger_ui_extra_configuration :

api_platform:
    openapi:
        swagger_ui_extra_configuration:
            deepLinking: true

Avec cette option activée, le fragment d’URL se met à jour pendant la navigation dans l’UI, et coller ou partager l’URL ouvre la même opération. Utile quand on écrit de la doc qui pointe directement vers un endpoint spécifique.

Validation stricte des paramètres de requête

La 3.3 renforce le validateur de paramètres de requête : les paramètres non déclarés sur l’opération renvoient maintenant une réponse 400 au lieu d’être silencieusement ignorés. Ce comportement est opt-in :

api_platform:
    validator:
        query_parameter_validation: true

L’intention est de détecter les fautes de frappe et les mauvaises utilisations de l’API tôt. Si vous vous appuyez sur des paramètres de requête pass-through pour une logique personnalisée (logging, feature flags), vous devez les déclarer explicitement sur l’opération avant d’activer cela.

Les erreurs comme ressources

Avant la 3.2, la gestion des erreurs était en dehors du modèle de ressources. Les exceptions étaient interceptées par un event listener Symfony et converties en réponse, avec un contrôle limité sur la forme de la sortie.

La 3.2 fait des erreurs des classes ApiResource de première classe conformes à la RFC 9457 (Problem Details for HTTP APIs). La classe d’erreur intégrée est ApiPlatform\ApiResource\Error, et on peut créer la sienne :

use ApiPlatform\Metadata\ApiResource;
use ApiPlatform\Metadata\ErrorResource;
use ApiPlatform\Metadata\Exception\ProblemExceptionInterface;

#[ApiResource]
#[ErrorResource]
class BookNotFoundError extends \RuntimeException implements ProblemExceptionInterface
{
    public function __construct(private readonly string $bookId)
    {
        parent::__construct("Book $bookId not found");
    }

    public function getType(): string
    {
        return '/errors/book-not-found';
    }
}

Quand cette exception est levée n’importe où dans la couche d’état, API Platform l’intercepte, la sérialise comme une réponse Problem Detail, et génère un schéma OpenAPI approprié pour elle. Le type d’erreur, le titre, le détail et le statut font tous partie du contrat de la ressource — pas des chaînes codées en dur dans un listener.

Les sous-ressources sans les contournements

Les sous-ressources existaient en 2.x mais ont été supprimées en 3.0 parce qu’elles étaient étroitement couplées à l’ancien modèle de data provider et ne pouvaient pas être proprement mappées à la nouvelle architecture orientée opération. La 3.2 les réintroduit d’une façon qui s’intègre.

Une sous-ressource est une ressource accessible via l’URI d’une ressource parente. En 3.2, elle est déclarée directement sur la ressource enfant en utilisant uriTemplate :

use ApiPlatform\Metadata\ApiResource;
use ApiPlatform\Metadata\GetCollection;

#[ApiResource(
    operations: [
        new GetCollection(
            uriTemplate: '/books/{bookId}/reviews',
            uriVariables: [
                'bookId' => new Link(fromClass: Book::class),
            ],
        ),
    ]
)]
class Review
{
    // ...
}

Le descripteur Link rend la relation explicite. Le provider reçoit bookId dans $uriVariables et peut l’utiliser pour délimiter la requête. Pas d’inférence magique, pas de jointures implicites — la structure d’URI et l’accès aux données sont tous les deux déclarés.

canonical_uri_template pour plusieurs chemins d’accès

Quand une ressource est accessible via plusieurs URI (un endpoint direct et un endpoint de sous-ressource), OpenAPI doit savoir quelle URI est canonique pour les liens $ref. La 3.2 utilise le uriTemplate de niveau supérieur sur ApiResource comme URI canonique par défaut. Pour plus de contrôle, l’option canonical_uri_template peut être passée via extraProperties sur n’importe quelle opération pour la définir explicitement.

#[ApiResource(
    uriTemplate: '/reviews/{id}',
    operations: [
        new Get(),
        new GetCollection(
            uriTemplate: '/books/{bookId}/reviews',
            uriVariables: ['bookId' => new Link(fromClass: Book::class)],
        ),
    ]
)]
class Review {}

La spec OpenAPI générée utilise l’URI canonique pour les références de schéma, gardant le document cohérent quand une ressource apparaît sous plusieurs chemins.

Types union et intersection

La 3.2 ajoute le support des types union et intersection PHP dans la couche de métadonnées. Une propriété déclarée comme Book|Magazine génère un schéma oneOf approprié dans OpenAPI. C’était auparavant non supporté — on devait tomber sur un mixed non typé ou annoter la propriété manuellement.

Les event listeners rendus optionnels

Le dernier shim de compatibilité venu de la 2.x était la possibilité d’utiliser les event listeners Symfony sur les événements kernel.request et kernel.view pour intercepter le flux de données d’API Platform. La 3.2 ne les supprime pas, mais introduit un moyen de s’en passer : passer event_listeners_backward_compatibility_layer: false dans la configuration d’API Platform désactive entièrement les hooks basés sur les événements. Le remplacement est un provider ou processor décoré par un autre provider ou processor. Le hook basé sur les événements était avec état, dépendant de l’ordre, et court-circuitait entièrement le contexte d’opération. Les providers décorés reçoivent l’objet opération et peuvent appeler le provider interne quand ils sont prêts.

Le modèle d’état est maintenant complet

La 3.0 a introduit l’architecture. La 3.1 a ajouté la séparation ressource/entité. La 3.2 ferme les lacunes restantes : les erreurs ont un contrat de ressource, les sous-ressources ont un modèle de déclaration propre, et la couche d’état couvre désormais tous les points d’extension que les event listeners géraient autrefois. Les shims 2.x existent encore, mais s’en passer n’est plus qu’une ligne de configuration.

La séparation ressource/entité

En 2.x, API Platform fonctionnait mieux quand votre ressource API et votre modèle de persistance étaient la même classe. Utiliser un DTO comme surface API était possible via le système Input/Output DTO, mais ce système a été supprimé en 3.0 — il compliquait le modèle d’état sans apporter suffisamment de bénéfices.

La 3.1 le remplace par quelque chose de plus propre. Le paramètre stateOptions d’une opération accepte un objet DoctrineOrmOptions qui pointe vers une entité différente :

use ApiPlatform\Metadata\ApiResource;
use ApiPlatform\Metadata\GetCollection;
use ApiPlatform\Doctrine\Orm\State\Options;

#[ApiResource(
    operations: [
        new GetCollection(
            stateOptions: new Options(entityClass: BookEntity::class),
        ),
    ]
)]
class BookDto
{
    public string $title;
    public string $author;
}

Le provider reçoit les objets BookEntity de Doctrine et la couche de sérialisation les mappe sur BookDto. Les filtres Doctrine, la pagination et le tri fonctionnent tous sur BookEntity. La surface API expose BookDto. Les deux peuvent évoluer indépendamment.

Ça compte plus qu’il n’y paraît. Votre modèle de persistance accumule des champs internes, des relations et des colonnes qui n’ont aucune raison d’apparaître dans votre API. Avant la 3.1, on les exposait quand même ou on construisait un normaliseur élaboré pour les cacher. Maintenant on déclare ce que l’API expose comme classe distincte et on laisse le framework gérer la correspondance.

Un PUT conforme à la spec

Depuis la version 1.0, le handler PUT d’API Platform mettait à jour des ressources existantes. Créer une ressource via PUT — ce que la spec HTTP autorise explicitement — n’était pas supporté. La 3.1 ajoute la création basée sur l’uriTemplate :

#[Put(
    uriTemplate: '/books/{id}',
    allowCreate: true,
)]

Avec allowCreate: true, un PUT vers une URI qui n’existe pas crée la ressource au lieu de retourner une 404. L’identifiant vient de l’URI, pas du corps de la requête. C’est ce que la RFC 9110 décrit pour PUT : “Si la ressource cible n’a pas de représentation courante et que le PUT en crée une avec succès, le serveur d’origine DOIT informer le user agent en envoyant une réponse 201 (Created).”

C’est un petit paramètre, mais il ouvre API Platform à des cas d’usage — création idempotente, identifiants assignés par le client — qui nécessitaient auparavant un contrôleur personnalisé.

Les erreurs de dénormalisation collectées, pas jetées

Avant la 3.1, les erreurs de désérialisation s’arrêtaient au premier problème. Envoyer un corps de requête avec cinq champs invalides renvoyait une erreur sur le premier. On le corrigeait, on renvoyait, on trouvait le deuxième. À répéter cinq fois.

La 3.1 ajoute une option collect_denormalization_errors sur l’opération qui change ce comportement :

#[Post(collectDenormalizationErrors: true)]

Avec cette option activée, API Platform intercepte toutes les erreurs de type et les violations de contraintes pendant la désérialisation et les retourne sous forme de liste structurée dans la réponse, formatée de la même façon que les erreurs de validation. Un seul aller-retour, une vue complète.

ApiResource::openapi remplace openapiContext

L’ancien paramètre openapiContext acceptait un tableau brut fusionné dans le schéma OpenAPI généré — pratique mais non typé. La 3.1 introduit un paramètre openapi de premier ordre qui accepte un objet OpenApiOperation :

use ApiPlatform\OpenApi\Model\Operation;
use ApiPlatform\OpenApi\Model\RequestBody;

#[Post(
    openapi: new Operation(
        requestBody: new RequestBody(
            description: 'Créer un livre',
            required: true,
        ),
        summary: 'Créer une nouvelle entrée livre',
    )
)]

L’ancien tableau openapiContext fonctionne encore mais est déprécié. La nouvelle approche est typée, compatible avec l’autocomplétion IDE, et se valide à la construction plutôt qu’à la génération du schéma. Les backed enums PHP 8.1 obtiennent également une génération de schéma OpenAPI correcte en 3.1 — un champ typé comme backed enum produit un schéma avec des valeurs enum et le type correct, sans annotation supplémentaire.

Le pattern est clair

La 3.0 a établi l’architecture. La 3.1 montre ce que cette architecture permet : une séparation propre ressource/entité sans système DTO parallèle, une sémantique HTTP correcte selon la RFC, un meilleur rapport d’erreurs. Aucune de ces fonctionnalités n’aurait été aussi propre à implémenter sur le modèle data provider de la 2.x. Les features de la 3.1 sont la première preuve que la réécriture était la bonne décision.

L’ancien modèle avait une fuite conceptuelle. DataProviderInterface et DataPersisterInterface étaient appelés pour chaque requête HTTP, mais le provider recevait le contexte de l’opération comme un indice — pas comme un contrat. Un provider de collection et un provider d’item étaient des interfaces distinctes, mais les deux vivaient dans le même seau mental : “choses qui retournent des données.” La couche HTTP savait ce qui était demandé ; le provider devait reconstruire cette connaissance à partir d’indices passés dans le tableau $context.

La 3.0 inverse le modèle. Les opérations sont déclarées en premier. L’accès aux données est câblé aux opérations.

Les state providers remplacent les data providers

L’ancien DataProviderInterface a disparu. Le remplaçant est ProviderInterface :

use ApiPlatform\State\ProviderInterface;
use ApiPlatform\Metadata\Operation;

class BookProvider implements ProviderInterface
{
    public function provide(Operation $operation, array $uriVariables = [], array $context = []): object|array|null
    {
        if ($operation instanceof CollectionOperationInterface) {
            return $this->repository->findAll();
        }

        return $this->repository->find($uriVariables['id']);
    }
}

La différence n’est pas syntaxique. En 2.x, on enregistrait un provider et API Platform l’appelait pour toute ressource correspondante. En 3.0, on lie un provider à une opération spécifique. Le provider n’a plus à deviner ce qui l’a déclenché — l’objet opération qu’il reçoit est le contrat.

Les state processors remplacent les data persisters

DataPersisterInterface avait le même problème côté écriture : une seule classe gérant la création, la mise à jour et la suppression, les distinguant en inspectant la méthode HTTP ou l’état de l’objet. ProcessorInterface reçoit l’opération comme argument typé :

use ApiPlatform\State\ProcessorInterface;
use ApiPlatform\Metadata\Operation;

class BookProcessor implements ProcessorInterface
{
    public function process(mixed $data, Operation $operation, array $uriVariables = [], array $context = [])
    {
        $this->entityManager->persist($data);
        $this->entityManager->flush();

        return $data;
    }
}

Plus utile encore : on peut lier un processor différent par opération. L’opération de suppression en reçoit un qui supprime. L’opération de création en reçoit un qui valide et stocke. Pas de switch, pas d’inspection de méthode, pas de classe partagée qui essaie d’être trois choses à la fois.

Les opérations déclarées explicitement en attributs PHP 8.1

L’autre moitié de la 3.0 est la couche de métadonnées. Les annotations Doctrine sont remplacées par des attributs natifs PHP 8.1, et chaque opération est déclarée explicitement sur la classe ressource :

use ApiPlatform\Metadata\ApiResource;
use ApiPlatform\Metadata\Get;
use ApiPlatform\Metadata\GetCollection;
use ApiPlatform\Metadata\Post;

#[ApiResource(
    operations: [
        new GetCollection(provider: BookProvider::class),
        new Get(provider: BookProvider::class),
        new Post(processor: BookProcessor::class),
    ]
)]
class Book
{
    // ...
}

C’est plus verbeux que @ApiResource avec ses valeurs par défaut magiques. C’est aussi explicite. On sait exactement quelles opérations HTTP existent pour cette ressource, ce qui récupère les données, ce qui les écrit, et où vit la logique. Les valeurs par défaut de la 2.x étaient pratiques jusqu’au jour où il fallait en surcharger une sans réussir à déterminer quel service décorer sans lire le code source.

PHP 8.1 n’était pas un hasard

L’exigence stricte pour PHP 8.1 est structurante. Les callables de première classe rendent l’enregistrement des filtres plus propre. L’immuabilité des métadonnées d’opération est assurée par un pattern de clonage (méthodes withX()) qui s’appuie sur les arguments nommés et les propriétés de constructeur promues — des fondations PHP 8.0 sur lesquelles l’architecture s’appuie massivement.

Plus concrètement : l’expression complète de l’architecture 3.0 — opérations typées, providers scopés à l’opération, métadonnées explicites — avait besoin de la 8.1 pour ne pas ressembler à des contournements. Abandonner PHP 7.x et 8.0 n’était pas une décision de nettoyage.

La migration est un vrai travail

Le passage de 2.x à 3.0 n’est pas un simple bump de version. Chaque DataProvider devient un ProviderInterface. Chaque DataPersister devient un ProcessorInterface. Les annotations deviennent des attributs. Les normaliseurs et filtres personnalisés peuvent nécessiter une restructuration. Le guide de mise à jour documente tout cela, mais “documenté” ne veut pas dire “rapide.”

Ce qu’on obtient de l’autre côté est une architecture qui passe à l’échelle sans la complexité ambiante de la 2.x : plus besoin de deviner quelle interface implémenter, plus de chaînes $this->supports(), plus de valeurs par défaut invisibles qui surchargent silencieusement la config explicite.

La 3.0 est l’API Platform qu’on concevrait de zéro en sachant ce qu’on sait après des années de 2.x. Le prix est la migration. Le numéro de version est honnête là-dessus.