Sortie d'API Platform 2.6 !

Découvrez la version originale de cet article ici.

Kévin Dunglas a annoncé ce matin la sortie de l’alpha d’API Platform 2.6 à la SymfonyWorld ! Cette version est le résultat de plus d’un an de travail et d’une centaine de commits. Elle comporte une impressionnante liste de nouvelles fonctionnalités, n'hésitez pas à consulter les changelogs (bibliothèque Coredistribution) pour découvrir la liste dans son intégralité. 

2.6

Vous allez découvrir dans cet article les fonctionnalités majeures de cette version, vous pouvez aussi consulter les slides de la SymfonyWorld pour plus de détails :

Support de PHP 8

PHP 8 est sorti la semaine dernière avec une liste impressionnante de nouvelles fonctionnalités. Parmi elles, les attributs, qui vont changer la donne pour API Platform qui s'appuyait beaucoup sur les annotations. Avec API Platform 2.6, vous pouvez utiliser toutes les classes d’annotations comme attributs PHP 8 : 

<?php

namespace App\Entity;

use ApiPlatform\Core\Annotation\ApiResource;

#[ApiResource]
class Book
{
    public function __construct(
        public string $id,
        public string $title
    ) {}
}

API Platform est désormais totalement compatible avec PHP 8 (toutes les dépréciations ont été corrigées), et PHP 8 est maintenant installé par défaut dans la distribution du framework !

Support de Next.js et Nuxt.js

API Platform est livré avec un outil très pratique pour créer les applications clients : le générateur de clients. Le générateur utilise la documentation Hydra ou OpenAPI (de manière expérimentale) de l’API pour générer des applications utilisant diverses technologies orientées client. Cela fonctionne avec n’importe quelle API documentée à l’aide de ces formats, et pas seulement avec les APIs utilisant le composant côté serveur d’API Platform !

La génération de définitions TypeScript ainsi que de Progressive Web Apps construites avec React Native, React/Redux, Vue.js, Quasar et Vuetify était déjà prise en charge. Dans API Platform 2.6, le support de Next.js a été ajouté par Grégory Copin, l’un de nos coopérateurs !

Next.js est le framework de référence dans l’écosystème React. Il est simple d’utilisation, supporte le Server-Side Rendering, dispose d'un système de routage par page simple et puissant, et prend en charge un large éventail de fonctionnalités. La distribution d’API Platform a aussi été mise à jour pour utiliser Next.js par défaut. Un conteneur Docker et une définition Docker Compose lanceront automatiquement un squelette d’app Next.js et vous serez ainsi en mesure de créer vos pages et vos formulaires en exécutant qu'une seule commande !

API Platform Admin est aussi désormais intégré dans cette app Next.js, à l’adresse /admin

Vous préférez utiliser Vue à la place de React ? Nous avons pensé à vous ! Dans API Platform 2.6, vous trouverez aussi un générateur Nuxt.js. Nuxt.js est semblable à Next.js, mais utilise Vue et comme API Platform, c’est conçu par des français !

Simplification de la distribution avec le serveur web Caddy

Dans la version 2.6 d’API Platform, la distribution a été totalement remaniée. API Platform prend en charge de nombreuses fonctionnalités avancées directement prêtes à l'emploi, comme les protocoles Mercure et Vulcain. Pour prendre en charge ces fonctionnalités, API Platform est livré avec de nombreux conteneurs Docker :

  • PHP-FPM
  • NGINX
  • Un conteneur pour générer des certificats TLS
  • Un reverse proxy Vulcain
  • Le Hub Mercure
  • PostgreSQL
  • Un conteneur Node.js pour le générateur de client
  • Un conteneur Node.js pour l’app admin

Dans API Platform 2.6, tout est simplifié ! Tout d’abord, nous sommes passés de NGINX au serveur web Caddy. Caddy est rapide, extensible et riche en fonctionnalités. Par exemple, il génère automatiquement des certificats TLS à la fois en production et sur l’environnement de développement local, et supporte nativement PHP-FPM. Nous avons également créé des modules Caddy pour Mercure et Vulcain ! Nous sommes aussi en train de travailler avec l’équipe de Caddy pour créer un module de cache HTTP qui remplacera Varnish.

Comme expliqué plus haut, nous avons également remplacé Create React App par Next.js et fusionné les conteneurs du client et de l’admin. Le résultat est une configuration très simplifiée :

  • PHP-FPM
  • Serveur web Caddy
  • PostgreSQL (facultatif)
  • Conteneur Next.js (facultatif)

La définition Docker Compose incluse dans la distribution supporte désormais un mode “production”.

Meilleure configuration

Jusqu’à présent, il n’était pas possible de définir une configuration globale par défaut appliquée à toutes les ressources et toutes les opérations. Vous deviez copier votre configuration dans toutes les définitions de ressource. Avec API Platform 2.6, vous pouvez définir une configuration globale par défaut

# config/packages/api_platform.yaml
api_platform:
    defaults:
        itemOperations: ["get"]
        collectionOperations: ["get"]
        mercure: true

La configuration précédente désactive toutes les routes d'écriture de l'API, et active le support de Mercure (API asynchrone) pour toutes les ressources existantes !

Contrôle d'accès aux propriétés

Jusqu’à présent le contrôle d’accès d’API Platform se basait uniquement sur les ressources. Dans la v2.6, il peut désormais s’appliquer directement au niveau des propriétés :

<?php

namespace App\Entity;

use ApiPlatform\Core\Annotation\ApiResource;
use ApiPlatform\Core\Annotation\ApiProperty;

#[ApiResource]
class Book
{
    #[\ApiProperty(security: "is_granted('ROLE_ADMIN')"]
    public $adminOnlyProperty; 
}

Grâce à cette règle, la propriété adminOnlyProperty sera sérialisée uniquement pour les utilisateurs disposant du rôle admin ! Les autres utilisateurs ne seront pas en mesure de la voir. 

Composant ActivityPub

Comme vous vous en doutez, nous sommes préoccupés par l'état actuel du web et pensons que nous devons agir pour le décentraliser à nouveau.

ActivityPub est une spécification éditée par le W3C débloquant l'interopérabilité entre les applications de réseaux sociaux. Elle fait partie des solutions permettant de lutter contre la censure et de se passer des plateformes fermées des GAFAM. ActivityPub est déjà implémentée par de nombreux logiciels comme Mastodon (une alternative à Twitter), Peertube (une alternative à Youtube), PixelFed (une alternative à Instagram), Mobilizon (une alternative à Meetup)… Cet écosystème est nommé le Fediverse.

Dans API Platform 2.6, nous avons introduit un nouveau composant expérimental permettant l’ajout du support d’ActivityPub à n’importe quelle application API Platform ou Symfony ! Il est désormais beaucoup plus simple qu'auparavant de construire des applications fédérées et de faire grandir le Fediverse !

Communauté

La plus grande force d’API Platform, c’est sa communauté d’utilisateurs·trices et de contributeurs·tices ! Pour remercier notre communauté, un encart dédié à la communauté a été ajouté sur le site d’API Platform. Découvrez en détails cette section dans cet article. N'oubliez pas également qu’il est encore temps de réclamer votre t-shirt créé à l’occasion du Hacktoberfest ! Le formulaire ferme bientôt, ne tardez pas !  

API Platform 3

La prochaine version d’API Platform sera la 3 ! Nous sortirons API Platform 2.7 en même temps. API Platform 3 sera essentiellement la même que la version 2.7 moins la couche de rétrocompatibilité avec le code déprécié. API Platform 3 mettra en avant les sous-ressources ! Elles prendront en charge notamment les opérations d'écriture, la configuration générale est également en cours de réorganisation.

Aussi, pour réduire la charge de maintenance, API Platform 3 supportera uniquement PHP 8 et Symfony 5.2+. Anticipez dès à présent vos mises à jour !

Divers

D'autres fonctionnalités n’ont pas été citées dans cet article : notre sous-système GraphQL a gagné de nombreuses nouvelles fonctionnalités (y compris le support des souscriptions grâce à Mercure et une pagination par page), le bridge MongoDB supporte désormais le protocole Mercure, le builder OpenAPI a été totalement réécrit, les identifiants composés sont plus faciles à manipuler… Lisez les changelogs (core, distribution) pour tout découvrir ! 

Un énorme merci à toutes les personnes ayant contribué au code et à la documentation d’API Platform 2.6 ! Rien de tout cela ne serait possible sans votre aide. 

Essayez dès à présent l’alpha de cette version et signalez-nous le moindre bug ! N’oubliez pas également de mettre une étoile sur Github

Les-Tilleuls.coop reste disponible pour le développement de vos projets ou votre montée en compétences sur API Platform