L’API qui continuait de s’éloigner

Il y a quelques années, j’avais obtenu une clé d’API développeur. L’idée était d’écrire un client minimal pour cocher des épisodes sans jamais toucher l’interface de l’app. J’ai fait quelques requêtes, ça marchait, mais la lenteur venait de l’API et non de l’app — un client maison ne réglerait rien. J’ai laissé tomber. Quelques mois plus tard, les requêtes étaient de toute façon bloquées — je n’ai jamais su si ma clé avait été révoquée en silence ou si l’API avait changé sans prévenir.

TVTime est une application gratuite sans modèle de monétisation évident — que l’API soit la première victime d’une réduction de coûts d’infrastructure, c’était compréhensible. J’ai continué à utiliser l’app, à attendre.

Quelques années plus tard, je commençais à jouer avec Home Assistant et l’idée d’un dashboard de mes épisodes en cours me paraissait évidente. J’ai renvoyé une demande d’accès API en mentionnant ce cas d’usage. Cette fois la réponse était claire : plus de clé d’API pour le public.

Second échec. Et en y repensant, TVTime n’avait pas vraiment évolué depuis des années — si tant est qu’il n’avait pas régressé.

Le dimanche qui a rompu l’habitude

Le troisième signal est arrivé un dimanche après-midi. Spinner. Erreur. Spinner. J’ai fermé l’app et j’ai pensé qu’il était temps de la remplacer.

Je suivais trois choses : des animés, des séries télévisées et des films. Les animés étaient la priorité — j’en regarde davantage, le calendrier de diffusion est fragmenté sur plusieurs plateformes, et savoir ce qui sort dans la semaine est vraiment utile. Deux exigences rendraient un remplacement réellement utilisable : un calendrier hebdomadaire des sorties et une synchronisation multi-appareils (téléphone et ordinateur, au minimum).

Je me suis donné un week-end pour faire un POC. La stack sur laquelle je me suis appuyé : React 19, TypeScript, Vite, Firebase Auth et Firestore. Pas parce que c’est une combinaison à la mode, mais parce qu’elle résout le problème de synchronisation sans faire tourner un backend. Firestore fournit un document store en temps réel ; Firebase Auth gère la connexion entre les appareils ; le navigateur fait le reste. Je préférais payer la latence des lectures Firestore plutôt que de construire et maintenir un serveur API pour un projet personnel avec exactement un utilisateur.

Le projet s’appelle Miru. En japonais, ça signifie « regarder ».

Trois formats, trois API

La première vraie décision portait sur les API à utiliser. Les animés, les séries et les films vivent dans des écosystèmes de données séparés, et faire semblant du contraire m’aurait coûté des semaines.

Pour les animés, AniList s’impose. Il expose une API GraphQL, couvre l’essentiel du medium et inclut directement les calendriers de diffusion. Une seule requête avec une plage de dates retourne les prochains épisodes pour une liste d’identifiants. Un seul appel réseau pour toute la semaine. Je ne m’attendais pas à ce que ce soit aussi propre.

Pour les séries et les films, TMDB est la référence. Son API REST v3 est bien documentée, stable, et couvre le catalogue international que d’autres bases de données ratent. La contrepartie : pas d’endpoint de planning par lot. J’appelle l’endpoint de saison par série, je filtre sur la semaine en cours, et je collecte les résultats.

Les titres d’épisodes pour les animés viennent d’une troisième source : Jikan , qui agrège MyAnimeList. AniList n’a pas toujours les titres d’épisodes, surtout pour les séries plus anciennes. Quand un item suivi dispose d’un MAL ID (qu’AniList expose), je récupère la liste des épisodes depuis Jikan et j’injecte les titres. C’est un enrichissement optionnel — le calendrier fonctionne sans, mais la différence entre « Épisode 7 » et « La Troisième Trahison » vaut bien quelques requêtes supplémentaires.

Une requête pour toute la semaine

Le calendrier hebdomadaire est la fonctionnalité qui justifie le projet. Chaque dimanche, je veux voir ce qui sort dans les sept prochains jours dans tout ce que je regarde, sans ouvrir quatre applications différentes.

Côté AniList, c’est efficace. Une seule requête GraphQL prend la liste des identifiants AniList de mes animés en cours et une plage de dates, et retourne tous les épisodes prévus dans cette fenêtre. Une requête, toutes les données.

query AiringSchedule($ids: [Int], $start: Int, $end: Int) {
  Page {
    airingSchedules(
      mediaId_in: $ids
      airingAt_greater: $start
      airingAt_lesser: $end
    ) {
      mediaId
      episode
      airingAt
    }
  }
}

Côté TMDB, c’est moins élégant. Pas d’endpoint de planning par lot, donc j’appelle l’endpoint de saison par série et je filtre localement. Pour dix séries en cours, ça fait dix requêtes en parallèle — tolérable, et les limites de débit de TMDB sont suffisamment généreuses pour ne pas s’en préoccuper.

L’enrichissement Jikan tourne en dernier, après l’assemblage des données AniList. Pour chaque épisode planifié où j’ai un MAL ID, je récupère la liste depuis Jikan et j’injecte le titre. Je mets ces données en cache par session pour éviter de récupérer la même liste deux fois.

Pas de serveur, pas d’ops

Firestore est l’élément qui rend ce projet viable. Ma bibliothèque — quelles séries je suis, où j’en suis, quels épisodes j’ai cochés — tient dans un seul document Firestore par utilisateur. Il se charge à l’authentification, se sauvegarde à chaque modification avec un debounce d'1,5 seconde pour ne pas saturer le quota gratuit, et se synchronise automatiquement entre les appareils.

Les règles de sécurité tiennent en deux lignes : lecture et écriture autorisées uniquement si request.auth.uid == userId. Pas de backend, pas de middleware d’autorisation, pas de rotation de token à gérer.

L’hébergement suit la même logique : l’app est déployée sur Vercel , connectée au dépôt GitHub. Chaque push sur main déclenche un build et une mise en production automatique. Zéro configuration serveur, zéro pipeline à maintenir.

La seule chose que Firestore ne résout pas, c’est le cold start. Le premier chargement sur un nouvel appareil attend l’initialisation du SDK Firebase et l’arrivée du document. Sur une bonne connexion, moins d’une seconde. Sur un réseau mobile, ça se sent. J’accepte ce compromis — un tracker personnel n’a pas besoin de l’architecture d’une plateforme de streaming. Le jour où il y aurait davantage d’utilisateurs, les choix faits ici mériteraient d’être ré-étudiés : backend dédié, cache, séparation des responsabilités. Mais ce jour-là n’est pas aujourd’hui.

L’extension qui a rendu la migration possible

Ce que je redoutais le plus en remplaçant TVTime, c’était l’import initial. J’avais quelques centaines d’entrées suivies sur plusieurs années. Migrer ça manuellement, non merci.

La solution : une extension de navigateur — pas pour un usage courant, mais pour la migration unique. Des scripts de contenu injectés sur les pages AniList , MyAnimeList et Crunchyroll détectent le titre du media depuis le slug d’URL, ajoutent un petit bouton « Ajouter à Miru » dans l’interface existante, et transmettent le titre à l’app au clic. L’extension pré-remplit le dialogue de recherche. On clique, on vérifie, on confirme.

J’ai migré ma liste AniList en vingt minutes environ. Mieux que prévu. Les séries et les films, j’ai dû les faire à la main, mais ces listes étaient plus courtes et la recherche est assez rapide pour que ce ne soit pas pénible.

L’extension est un build IIFE Manifest V3 — trois scripts de contenu séparés, un par plateforme, packagés pour Chrome et Firefox. Rien de complexe, mais ça a résolu le vrai point de friction qui sépare une migration qui se fait de celle qui ne se fait pas.

Ce que c’est devenu

Miru tourne en bêta depuis environ une semaine. Le calendrier hebdomadaire fonctionne. La page de stats est brute mais fonctionnelle. La recherche dans la bibliothèque est rapide. J’ai ouvert TVTime deux fois depuis lors, par réflexe, et refermé immédiatement les deux fois.

Ce que j’avais sous-estimé, c’est la valeur de posséder les données. Le document Firestore est le mien. Je peux l’exporter, le migrer, l’interroger, le brancher sur Home Assistant. C’était l’objectif d’il y a deux ans — une API fermée plus tard, je l’ai enfin.

Ce que j’avais surestimé, c’est la complexité des intégrations. AniList et TMDB sont de vraiment bonnes API. Leur documentation correspond au comportement réel, les réponses d’erreur disent quelque chose d’utile, et les limites de débit sont difficiles à atteindre en usage personnel. Trois heures d’expérimentation ont suffi pour construire des clients fonctionnels pour les deux.

L’extension m’a surpris. Je m’attendais à ce que ce soit la partie pénible. C’est finalement la plus satisfaisante : injecter un bouton, extraire un titre, fermer un onglet. Périmètre réduit, résultat immédiat. Le genre d’outil qui n’a besoin de fonctionner qu’une seule fois mais qui fait la différence entre une migration qui se fait et une qui ne se fait pas.

Une application sans HTTP

Depuis les débuts de Symfony, chaque application embarque un kernel basé sur HttpKernel, même quand elle ne sert aucun trafic HTTP. Un worker Messenger qui consomme depuis SQS traînait malgré lui toute la machinerie HTTP. 8.1 règle ça à la racine.

AbstractKernel et KernelTrait vivent maintenant dans le composant DependencyInjection. HttpKernel\Kernel étend AbstractKernel, donc les applications existantes sont entièrement compatibles. Ce qui est nouveau, c’est la possibilité d’écrire un kernel qui étend AbstractKernel directement, sans la couche HTTP.

Deux nouveaux bundles rendent ça utile immédiatement :

• ServicesBundle câble le DI, l’event dispatcher et le clock, sans dépendance HTTP.
• ConsoleBundle s’appuie dessus et ajoute le résolveur de commandes.

Pour une application CLI uniquement :

// config/bundles.php
return [
    Symfony\Component\Console\ConsoleBundle::class => ['all' => true],
];

namespace App;
use Symfony\Component\DependencyInjection\Kernel\AbstractKernel;
use Symfony\Component\DependencyInjection\Kernel\KernelTrait;

class Kernel extends AbstractKernel
{
    use KernelTrait;
}

Les auteurs de bundles héritent d’un attribut #[RequiredBundle] pour déclarer explicitement les dépendances entre bundles, avec un flag ignoreOnInvalid pour les dépendances optionnelles :

#[RequiredBundle(AcmeCoreBundle::class)]
#[RequiredBundle(AcmeUtilBundle::class, ignoreOnInvalid: true)]
class AcmeBlogBundle extends AbstractBundle {}

Rate limiting déclaratif

8.1 ajoute un attribut #[RateLimit] pour les controllers. Posé sur une action, il applique la limite configurée dans framework.rate_limiter et renvoie automatiquement un 429 avec Retry-After.

use Symfony\Component\HttpKernel\Attribute\RateLimit;

class ApiController extends AbstractController
{
    #[RateLimit('api')]
    public function index(): JsonResponse { /* ... */ }

    #[RateLimit('api', methods: ['POST', 'PUT'])]
    public function edit(): JsonResponse { /* ... */ }

    #[RateLimit('api', tokens: 5)]
    public function export(): JsonResponse { /* ... */ }
}

L’attribut est répétable, il est donc possible d’empiler deux politiques sur la même action. Par défaut, la clé de bucket combine l’IP client, la méthode HTTP et le path. Elle peut être remplacée par une expression pour des buckets par utilisateur :

use Symfony\Component\ExpressionLanguage\Expression;

#[RateLimit('per_account', key: new Expression('request.request.get("email")'))]
public function resetPassword(): Response { /* ... */ }

La politique fixed_window gagne anchor_at, qui aligne les resets sur un moment calendaire plutôt que sur la première requête. Pratique pour les quotas de facturation mensuelle :

framework:
    rate_limiter:
        api_quota:
            policy: 'fixed_window'
            limit: 10000
            interval: '1 month'
            anchor_at: '2026-01-05 00:00:00 UTC'

Injection de dépendances

Plusieurs améliorations DI arrivent dans 8.1.

Env vars en Closure ou Stringable. Les workers longue durée ont parfois besoin de rafraîchir des variables d’environnement entre les itérations. Autowirer une env var en Closure fournit une factory plutôt qu’une valeur figée :

class Worker
{
    public function __construct(
        #[Autowire(env: 'DB_URL')]
        private \Closure $dbUrl,

        #[Autowire(env: 'APP_NAME')]
        private string|\Stringable $appName = 'default',
    ) {}
}

#[AsTagDecorator]. Décorer tous les services portant un tag donné en posant un seul attribut sur la classe décorateur :

#[AsTagDecorator('app.handler')]
class LoggingHandler
{
    public function __construct(private object $inner) {}
}

Env vars avec des points dans le nom. Les noms comme DATABASE.PRIMARY.URL sont désormais valides, ce qui compte quand on consomme des variables structurées par des plateformes cloud.

Messenger

Messenger reçoit plusieurs ajouts concrets dans 8.1.

Batch fetching. La nouvelle option --fetch-size de messenger:consume réduit le nombre d’aller-retours vers le transport. Avec SQS (qui autorise jusqu’à 10 messages par appel), ça coupe une bonne partie de l’overhead à fort débit :

php bin/console messenger:consume async --fetch-size=8

Nom de type sérialisé personnalisé. Quand un consommateur non-Symfony identifie un message par une chaîne stable plutôt que par un nom de classe PHP, #[AsMessage] couvre ce cas :

#[AsMessage(serializedTypeName: 'crawler.vectorization_finished')]
final readonly class VectorizationFinished
{
    public function __construct(public string $crawlId) {}
}

Priorité AMQP par message. AmqpPriorityStamp définit la priorité sur un dispatch individuel plutôt qu’au niveau de la queue :

$bus->dispatch($message, [new AmqpPriorityStamp(5)]);

Contrôle du reset. --no-reset=100 exécute le reset des services tous les 100 messages plutôt qu’après chacun, ce qui réduit l’overhead des workers longue durée à grande échelle.

Idle timeout pour BatchHandler. Les batches partiels sont maintenant flushés après une période d’inactivité configurable, pas seulement quand le batch est plein.

Redis receiver listable. Le receiver Redis expose maintenant all() et find(), ce qui permet d’inspecter les messages en attente par programmation.

Console

Commandes méthodes. Plusieurs commandes peuvent cohabiter dans une même classe comme méthodes distinctes. Moins de boilerplate quand une fonctionnalité génère un groupe de commandes liées.

#[AskChoice]. Déclarer un prompt de choix interactif directement dans la signature de l’argument, avec support des enums :

#[AsCommand('app:create-user')]
class CreateUserCommand
{
    public function __invoke(
        #[Argument, AskChoice('Select a role', ['admin', 'editor', 'viewer'])]
        string $role,
    ): int { /* ... */ }
}

Validation sur #[Ask]. Les prompts interactifs acceptent maintenant des contraintes de validation :

public function __invoke(
    #[Argument, Ask('Enter your email:', constraints: [
        new Assert\NotBlank(),
        new Assert\Email(),
    ])]
    string $email,
): int { /* ... */ }

#[MapInput]. Mappe automatiquement les arguments et options d’une commande dans un DTO validé.

RawInputInterface. Donne accès aux tokens bruts de l’input, utile pour forwarder des arguments à un sous-processus sans les re-parser.

HttpClient

Connexions cURL persistantes (PHP 8.5+) : réutilisation du cache DNS et des sessions SSL entre les requêtes, ce qui réduit la latence pour les clients à haute fréquence.

GuzzleHttpHandler. Symfony HttpClient peut maintenant servir de transport Guzzle, ce qui permet au code existant utilisant Guzzle de bénéficier du retry, du mock et du scopage Symfony sans migration complète :

use Symfony\Component\HttpClient\GuzzleHttpHandler;

$guzzle = new \GuzzleHttp\Client(['handler' => new GuzzleHttpHandler()]);

Allowlist SSRF pour NoPrivateNetworkHttpClient. Passer une IP ou un range spécifique à autoriser à travers le blocage réseau privé :

$client = new NoPrivateNetworkHttpClient(HttpClient::create(), null, '10.0.0.42');

max_connect_duration. Un timeout limité à la phase de connexion uniquement, pour un contrôle plus fin sur les DNS lents et les handshakes TLS.

Mapping du payload de requête

#[MapRequestPayload] gère maintenant le multipart/form-data, ce qui permet d’avoir des propriétés UploadedFile dans les DTOs mappés :

class ProductDto
{
    public ?string $name = null;
    public ?UploadedFile $image = null;
}

public function upload(#[MapRequestPayload] ProductDto $data): Response { /* ... */ }

Les arguments variadiques permettent de mapper un tableau JSON directement en une série d’objets typés :

public function createPrices(#[MapRequestPayload] Price ...$prices): Response { /* ... */ }

validationGroups accepte maintenant une Expression ou une Closure pour une sélection de groupes dynamique. mapWhenEmpty: true déclenche la dénormalisation même sur un payload vide.

Formulaires

Le thème daisyUI 5 est maintenant inclus, ce qui couvre les frontends Tailwind sans thème personnalisé :

twig:
    form_themes: ['daisyui_5_layout.html.twig']

DateType en mode choice accepte une option labels pour renommer les selects année, mois et jour sans template personnalisé. Les checkboxes non cochées sont maintenant soumises automatiquement comme false plutôt qu’être absentes du payload, ce qui corrige une incohérence de longue date.

Sérialisation automatique des réponses

L’attribut #[Serialize] posé sur une méthode de controller sérialise automatiquement la valeur de retour dans une Response, en choisissant le format (JSON, XML) depuis le format de la requête. Fini les $this->json() manuels pour les endpoints API simples :

use Symfony\Component\HttpKernel\Attribute\Serialize;
use Symfony\Component\Serializer\Normalizer\DateTimeNormalizer;

final readonly class CreateProductController
{
    #[Serialize(
        code: 201,
        headers: ['X-Custom-Header' => 'abc'],
        context: [DateTimeNormalizer::FORMAT_KEY => 'd.m.Y H:i:s'],
    )]
    public function __invoke(): ProductCreated
    {
        return new ProductCreated(101);
    }
}

Une route avec {_format} retourne du JSON pour /products/42.json et du XML pour /products/42.xml. Les formats non supportés donnent un 415.

DeepCloner

DeepCloner arrive dans le composant VarExporter comme remplacement de Instantiator et Hydrator (tous deux dépréciés en 8.1). Il clone des graphes d’objets PHP complexes directement, sans le round-trip unserialize(serialize()), en préservant la sémantique copy-on-write pour les strings et les tableaux.

use Symfony\Component\VarExporter\DeepCloner;

// clone one-shot
$clone = DeepCloner::deepClone($originalObject);

// cloner réutilisable sur le même prototype
$cloner = new DeepCloner($prototype);
$clone1 = $cloner->clone();
$clone2 = $cloner->clone();

// clone vers une sous-classe compatible
$childDefinition = (new DeepCloner($definition))
    ->cloneAs(ChildDefinition::class);

Une fonction deepclone_hydrate() remplace le Hydrator déprécié :

$user = deepclone_hydrate(User::class, ['name' => 'Alice']);

DI, FrameworkBundle, Form et Cache (ArrayAdapter) l’utilisent tous en interne dans 8.1. Une extension C optionnelle (symfony/php-ext-deepclone) est disponible pour des performances natives.

Attribut #[Cache] amélioré

L’attribut #[Cache] sur les méthodes de controller gagne trois choses en 8.1.

Variables d’expression nommées. lastModified et etag exposent maintenant request (l’objet Request) et args (les arguments du controller sous forme de tableau), en remplacement de la fusion plate précédente qui causait des collisions de noms :

#[Cache(
    etag: "args['article'].computeETag()",
    lastModified: "args['article'].getUpdatedAt()",
    public: true,
)]
public function show(Article $article): Response { ... }

Support des closures pour lastModified et etag :

#[Cache(
    lastModified: static function (array $args, Request $request): \DateTimeInterface {
        return $args['post']->getUpdatedAt();
    },
    etag: static function (array $args, Request $request): string {
        return (string) $args['post']->getId();
    },
)]
public function show(Post $post): Response { ... }

Application conditionnelle via if (expression string ou closure retournant un bool). Mettre en cache une réponse uniquement quand la requête ne porte pas de paramètre preview :

#[Cache(
    public: true,
    maxage: 3600,
    if: static fn (array $args, Request $request): bool => !$request->query->has('preview'),
)]
public function show(Request $request): Response { ... }

L’attribut est aussi répétable, ce qui permet d’empiler plusieurs politiques avec des conditions différentes sur la même méthode.

JSON streaming et JsonPath

Value objects dans JsonStreamer. Une interface ValueObjectTransformerInterface couvre les types qui se sérialisent en scalaire et vice-versa. Il suffit de l’implémenter et de taguer le service :

/** @implements ValueObjectTransformerInterface<Money, string> */
class MoneyTransformer implements ValueObjectTransformerInterface
{
    public function transform(object $object, array $options = []): string
    {
        return $object->amount.' '.$object->currency;
    }

    public function reverseTransform(string $scalar, array $options = []): Money
    {
        [$amount, $currency] = explode(' ', $scalar);
        return new Money((int) $amount, $currency);
    }

    public static function getStreamValueType(): BuiltinType { return Type::string(); }
    public static function getValueObjectClassName(): string { return Money::class; }
}

Types date. DateInterval se sérialise en ISO 8601 (P2Y6M1DT12H30M5S), DateTimeZone en nom de timezone. L’option date_time_timezone gère la conversion à l’encode/decode.

Options par défaut via config :

framework:
    json_streamer:
        default_options:
            include_null_properties: true

Fonctions JsonPath personnalisées via #[AsJsonPathFunction] :

use Symfony\Component\JsonPath\Attribute\AsJsonPathFunction;

#[AsJsonPathFunction('upper')]
final class UppercaseFunction
{
    public function __invoke(mixed $value): ?string
    {
        return \is_string($value) ? strtoupper($value) : null;
    }
}

$result = $crawler->find('$.items[?upper(@.title) == "HELLO"]');

Validator

Support Clock dans les contraintes de comparaison. GreaterThan, GreaterThanOrEqual, LessThan, LessThanOrEqual et Range acceptent une ClockInterface. Avec MockClock, les expressions de date relatives comme -10 days se résolvent par rapport à un point fixe dans le temps, rendant la validation temporelle déterministe dans les tests.

Validators réentrants. Le pattern stateful avec initialize($context) posait des problèmes lors d’appels récursifs. Une nouvelle méthode validateInContext() remplace validate() + initialize() sur ConstraintValidatorInterface. Les validators qui étendent la classe abstraite ConstraintValidator n’ont rien à changer.

Contrainte Xml. Valide qu’une chaîne est du XML bien formé, avec validation optionnelle via schéma XSD qui reporte les erreurs individuelles avec numéros de ligne.

Vérification d’existence de propriété. ValidatorBuilder::enablePropertyMetadataExistenceCheck() lève une ValidatorException quand une contrainte cible une propriété inexistante, ce qui attrape les typos au warmup.

En résumé

8.1 est une version dense en fonctionnalités. Le kernel sans HTTP est la pièce architecturalement significative : elle fait de Symfony un choix crédible pour les applications CLI et worker purs, sans le poids de la couche HTTP. Tout le reste gravite autour de l’ergonomie : moins de boilerplate sur les controllers (#[Serialize], #[RateLimit], #[Cache] amélioré), moins de boilerplate sur les commandes (attributs ask, commandes méthodes), moins de friction dans Messenger (taille de batch, noms de types, priorité AMQP), un clonage profond plus rapide dans VarExporter, et un Validator qui comprend enfin le temps. Beaucoup d’irritants de longue date traités en une seule version.

Support du serveur MCP

Le Model Context Protocol est le standard émergent pour connecter des LLMs à des outils et sources de données externes. 4.3 embarque une intégration MCP expérimentale qui se mappe directement sur le modèle de ressources d’API Platform.

Deux nouveaux attributs dans ApiPlatform\Metadata gèrent l’exposition :

McpTool marque une opération comme outil MCP qu’un agent peut appeler :

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

#[ApiResource]
#[McpTool(name: 'list_books', description: 'Returns a list of available books')]
#[GetCollection]
class Book {}

McpResource expose une ressource comme contenu MCP adressable, identifié par une URI :

use ApiPlatform\Metadata\McpResource;

#[ApiResource]
#[McpResource(uri: 'books://{id}', mimeType: 'application/ld+json')]
class Book {}

Les deux attributs sont répétables et se composent avec les opérations API Platform existantes. Le format du serveur MCP est configurable :

api_platform:
    mcp:
        format: 'jsonld'

L’intégration vit dans un package séparé api-platform/mcp. Les collections sont supportées. Symfony et Laravel sont couverts.

Scalar comme UI de documentation

Swagger UI est l’interface de documentation par défaut depuis API Platform 2.x. 4.3 ajoute Scalar comme alternative opt-in. Scalar affiche les specs OpenAPI avec une interface plus moderne et une meilleure lisibilité pour les grandes APIs.

À activer dans la config (nécessite TwigBundle) :

api_platform:
    enable_scalar: true
    openapi:
        scalar_extra_configuration:
            theme: 'purple'
            darkMode: true

Sécurité avant le provider

Avant 4.3, l’expression security: d’une opération était évaluée après que le state provider avait déjà chargé l’objet depuis la base. Une requête non autorisée déclenchait quand même une requête Doctrine avant d’être rejetée. À grande échelle, ça comptait.

4.3 enregistre un nouveau décorateur AccessCheckerProvider avec une priorité 10, avant l’étape de lecture :

#[ApiResource]
#[Get(security: "is_granted('ROLE_ADMIN')")]
class Book {}

Le contrôle is_granted s’exécute maintenant avant toute requête base de données. La contrepartie : $object est null au stade pre_read. Les expressions qui dépendent de l’objet chargé — security: "object.getOwner() == user" — doivent passer à securityPostDenormalize, qui s’exécute toujours après le provider.

C’est un changement comportemental. À vérifier sur vos expressions de sécurité si elles référencent object.

ComparisonFilter

Un nouveau décorateur ComparisonFilter dans ApiPlatform\Doctrine\Orm\Filter enveloppe n’importe quel filtre d’égalité et ajoute les opérateurs de comparaison (gt, gte, lt, lte, ne) :

use ApiPlatform\Doctrine\Orm\Filter\ComparisonFilter;
use ApiPlatform\Doctrine\Orm\Filter\RangeFilter;
use ApiPlatform\Metadata\QueryParameter;

#[ApiResource]
#[QueryParameter(filter: new ComparisonFilter(new RangeFilter()), property: 'price')]
class Product {}

Les paramètres OpenAPI pour chaque variante d’opérateur sont générés automatiquement. Le filtre est marqué expérimental.

UuidFilter et support des relations imbriquées

Un nouveau UuidFilter dans ApiPlatform\Doctrine\Orm\Filter filtre les collections par propriétés UUID, y compris les relations imbriquées. L’IriFilter reçoit le même support dans cette version.

use ApiPlatform\Doctrine\Orm\Filter\UuidFilter;
use ApiPlatform\Metadata\ApiFilter;

#[ApiResource]
#[ApiFilter(UuidFilter::class, properties: ['author.uuid'])]
class Book {}

PartialSearchFilter avec contrôle de la casse

Le nouveau PartialSearchFilter dans ApiPlatform\Doctrine\Orm\Filter effectue une recherche partielle sur les chaînes. Par défaut, il encapsule la comparaison dans LOWER() pour des résultats insensibles à la casse. Passer caseSensitive: true désactive ce comportement :

use ApiPlatform\Doctrine\Orm\Filter\PartialSearchFilter;
use ApiPlatform\Metadata\QueryParameter;

#[ApiResource]
#[QueryParameter(filter: new PartialSearchFilter(caseSensitive: true), property: 'title')]
class Book {}

SortFilter ODM avec support des propriétés imbriquées

Un SortFilter arrive pour MongoDB (ODM) dans ApiPlatform\Doctrine\Odm\Filter, conçu exclusivement pour être utilisé avec le système Parameters. Il supporte les propriétés imbriquées nativement :

use ApiPlatform\Doctrine\Odm\Filter\SortFilter;
use ApiPlatform\Metadata\QueryParameter;

#[ApiResource]
#[QueryParameter(filter: new SortFilter(), property: 'department.name')]
class Employee {}

Les entités Doctrine readonly perdent PUT et PATCH automatiquement

Si une entité Doctrine est déclarée en lecture seule avec #[ORM\Entity(readOnly: true)], API Platform supprime maintenant automatiquement les opérations PUT et PATCH de sa définition de ressource. Pas besoin de liste d’opérations manuelle :

use ApiPlatform\Metadata\ApiResource;
use Doctrine\ORM\Mapping as ORM;

#[ApiResource]
#[ORM\Entity(readOnly: true)]
class AuditLog {}

GET, GetCollection et DELETE restent disponibles. Seules les opérations d’écriture sont retirées.

Préfixe de namespace pour les makers

Le bundle Symfony accepte une nouvelle clé de configuration qui préfixe toutes les classes générées par les makers d’API Platform :

api_platform:
    maker:
        namespace_prefix: 'Api'

Avec ce réglage, make:api-resource génère les classes sous App\Api\ au lieu de App\.

Valeurs par défaut sur QueryParameter

QueryParameter accepte maintenant une option default qui fournit une valeur de repli quand le paramètre est absent de la requête :

use ApiPlatform\Metadata\QueryParameter;

#[ApiResource]
#[GetCollection]
#[QueryParameter(key: 'order', default: 'asc')]
class Book {}

Validation UUID et ULID sur les paramètres

Les paramètres de requête et headers déclarés avec un format uuid ou ulid sont maintenant validés automatiquement. Les identifiants mal formés sont rejetés avant d’atteindre le state provider, sans contrainte supplémentaire à ajouter.

ProblemExceptionInterface

Les exceptions personnalisées peuvent maintenant implémenter ProblemExceptionInterface pour mapper directement vers les champs RFC 7807 Problem Details (type, title, detail et membres d’extension). Auparavant, cela nécessitait un normalizer d’exception personnalisé.

Headers LDP

API Platform ajoute maintenant automatiquement les headers de réponse Accept-Post et Allow sur les endpoints de collection et d’item, conformément à la spécification Linked Data Platform . Cela améliore la découvrabilité pour les clients hypermedia qui s’appuient sur ces headers pour déterminer quelles opérations sont disponibles sur une ressource donnée.

Breaking changes

Quelques changements comportementaux à connaître avant de migrer :

• La sécurité s’exécute avant le provider. Les expressions qui référencent object recevront null. À déplacer vers securityPostDenormalize.
• Les filtres Doctrine requièrent un property explicite. Un attribut property manquant lève maintenant une exception au lieu d’échouer silencieusement.
• Le @type JSON-LD avec output et itemUriTemplate utilise un nom de classe différent pour être sémantiquement cohérent.