Un nom par version d'API, et des groupes à écarter

Nouveau dans Symfony 8.2 (en développement). Les groupes de sérialisation choisissent quelles propriétés sortent ; ils ne disaient rien de comment elles s'appellent. Une API qui change de version tout en gardant l'ancienne finissait donc par une seconde classe, ou par une boucle qui renomme les clés à la main après le serializer.

Un nom par groupe

#[SerializedName] et #[SerializedPath] deviennent répétables et acceptent un argument groups :

#[Groups(['v1', 'v2'])]
#[SerializedName('product_name', groups: 'v1')]
public string $name;

Sérialisée avec le groupe v1, la propriété sort sous product_name ; avec v2, sous name. Un nom déclaré sans groupe vaut pour tous, et sert de repli. Cela marche aussi dans l'autre sens, à la désérialisation.

Écarter un groupe

Le nouveau contexte AbstractNormalizer::IGNORED_GROUPS ('ignored_groups') retire les propriétés d'un groupe, même si elles appartiennent aussi à un groupe demandé :

$normalizer->normalize($livres, 'json', [
    AbstractNormalizer::GROUPS => 'v2',
    AbstractNormalizer::IGNORED_GROUPS => 'interne',
]);

À la différence de #[Ignore], qui retire une propriété partout, il ne vaut que là où on le passe. Avec un context builder, c'est withIgnoredGroups().

À faire

La librairie sert ses livres en trois endroits : l'API v1, que des partenaires lisent encore, l'API v2, et le back-office. LivresController rattrape à la main ce que les groupes ne savent pas dire : il renomme les clés de la v1 dans une boucle, et retire le stock de la v2 par unset().

1. Dans Livre, déclarez les noms de la v1 (nom, prix_centimes à plat) pour le seul groupe v1, sans changer ce que voient la v2 et le back-office.
2. Dans LivresController, faites de la v1 une simple sérialisation du groupe v1, et écartez le groupe interne de la v2 par le contexte.

Les trois requêtes de l'onglet « Requêtes » doivent répondre exactement comme avant.