Sortie d’API Platform 3.1
Publié le 23 janvier 2023
Après les retours plus que positifs sur la sortie de sa dernière version majeure, nous avons la joie de vous annoncer la disponibilité immédiate des versions 3.1, 3.0.11 et 2.7.7 d’API Platform !
Important : si vous n'avez pas encore effectué la mise à niveau vers la version 3.0, vous devez absolument la faire car la version 2.7 ne recevra plus que des mises à jour de sécurité. Si vous ne vous sentez pas à l'aise ou si vous pensez qu'il est trop difficile d'effectuer la mise à niveau, contactez-nous, nous pouvons vous aider ! Voyons maintenant ce que vous devez retenir de cette mise à jour.
Configuration des stateOptions #
Il est désormais possible de configurer des stateOptions sur une Operation. Cela permet d’aider à séparer la classe PHP que nous utilisons pour représenter la ressource API et la classe PHP utilisée pour la persistance dans un environnement Doctrine.
Cette fonctionnalité est le résultat de discussions menées avec notre coopérateur Loïc Vernet lorsqu'il travaillait sur le remplacement des endpoints avec API Platform 3 et avec Alex Rock lors du dernier Forum PHP.
Dans cette nouvelle version, la propriété stateOptions vous permet de spécifier une autre classe à utiliser en tant qu'entité Doctrine :
php
use ApiPlatform\Doctrine\Orm\Filter\OrderFilter;
use ApiPlatform\Doctrine\Orm\State\Options;
use ApiPlatform\Metadata\ApiFilter;
use ApiPlatform\Metadata\ApiResource;
use ApiPlatform\Tests\Fixtures\TestBundle\Entity\SeparatedEntity;
#[ApiResource(shortName: 'SeparatedEntity', stateOptions: new Options(entityClass: SeparatedEntity::class))]
class ResourceWithSeparatedEntity
{
public string $id;
#[ApiFilter(OrderFilter::class)]
public string $value;
}Le même mécanisme a été ajouté à Elasticsearch pour personnaliser l’index utilisé.
Conformité de PUT #
Notre implémentation actuelle de la méthode HTTP PUT n’est pas conforme aux normes.
Selon la spécification, une requête PUT doit créer ou remplacer la ressource à l'URL demandée. À partir d'API Platform 3.1, vous pouvez activer la création d'une ressource via PUT en utilisant allowCreate : true
Attention : préparez le changement de compatibilité ascendante en prévision d'API Platform 4 ! Dans cette future version, PUT remplacera les données. Pour s'assurer que votre code fonctionne de cette façon, nous vous recommandons de définir :
yaml
defaults:
extra_properties:
standard_put: trueVous serez ainsi prêt·e pour la prochaine version majeure. Dans API Platform 3.1, la valeur par défaut est false afin que le comportement attendu ne change pas. Retrouvez tous les détails de l'implémentation sur GitHub, merci à Kévin Dunglas pour avoir rendu cela possible !
Support des Enums #
Après une longue attente, les Enums sont désormais supportées dans OpenAPI, REST et GraphQL. Doctrine ORM et ODM ont tous deux un support pour les Enums à travers enumType qui est supporté par API Platform 3.0. Notre coopérateur Alan Poulain a ajouté son support à OpenAPI et GraphQL.
Purge du cache HTTP revisité #
Nous avons remanié notre clé de substitution pour le rendre agnostique en termes de fournisseur et nous avons ajouté un Purger pour Souin, un fournisseur de cache HTTP en Go qui fonctionne comme un module Caddy !
Amélioration de la personnalisation d'OpenAPI #
Dans les versions précédentes, personnaliser la documentation OpenAPI nécessitait souvent de décorer le service OpenApiFactory. Dans API Platform 3.1, vous pouvez utiliser l'option openapi avec un objet ApiPlatform\OpenApi\Model\Operation vous permettant ainsi d'utiliser exactement le même ValueObject que celui utilisé pour générer la documentation OpenAPI :
php
use ApiPlatform\Metadata\ApiResource;
use ApiPlatform\Metadata\Post;
use ApiPlatform\OpenApi\Model;
use App\Controller\RandomRabbit;
#[ApiResource]
#[Post(
name: 'create_rabbit',
uriTemplate: '/rabbit/create',
controller: RandomRabbit::class,
openapi: new Model\Operation(
summary: 'Create a rabbit picture',
description: '# Pop a great rabbit picture by color!\n\n',
requestBody: new Model\RequestBody(
content: new \ArrayObject([
'application/json' => [
'schema' => [
'type' => 'object',
'properties' => [
'name' => ['type' => 'string'],
'description' => ['type' => 'string']
]
],
'example' => [
'name' => 'Mr. Rabbit',
'description' => 'Pink Rabbit'
]
]
])
)
)
)]
class Rabbit
{
// ...
}
Cette option openapi prend également la valeur false pour supprimer votre opération de la documentation.
Collecte des erreurs de dénormalisation #
Depuis Symfony 5.4 et grâce à Grégoire Pineau, nous pouvons collecter les erreurs de type pendant la dénormalisation. Notre coopératrice Natacha a ajouté cette fonctionnalité en tant qu'option sur API Platform 3.1 :
php
use ApiPlatform\Metadata\ApiResource;
#[ApiResource(
collectDenormalizationErrors: true
)]
class Book
{
}Voici un aperçu de ce que vous pourrez découvrir dans cette nouvelle version, n'oubliez pas de consulter le CHANGELOG pour plus de détails ! Encore une fois, si vous avez besoin d’accompagnement ou d’une formation dans votre montée de version, n’hésitez pas à nous solliciter !
Nous profitons de ce billet pour vous annoncer qu’une nouvelle date a été annoncée pour un workshop API Platform 3 : j’aurais à nouveau le plaisir d’animer à Nantes le 9 février prochain une journée d’atelier consacrée à cette version. Inscrivez-vous dès maintenant, le nombre de places est limité !
