Programmation PHP avec Symfony/API

Doctrine

Sommaire

Pour créer une interface de programmation (API) REST avec Symfony, il existe plusieurs bibliothèques :

API Platform^[1], tout-en-un qui utilise les attributs PHP (ou des annotations en PHP < 8) des entités pour créer les APIs (donc pas besoin de créer des contrôleurs ou autres). Par défaut il permet de sérialiser les flux en JSON (dont JSON-LD, JSON-HAL, JSON:API), XML (dont HTML), CSV, YAML, et même en GraphQL^[2].
Sinon il faut combiner plusieurs éléments : routeur, générateur de doc en ligne et sérialiseur.

Programmation PHP avec Symfony

Introduction
Service
- Contrôleur
- Commande
Composant
- HttpClient
- Évènement
- Formulaire
- Mailer
- Stimulus
Bundle
- Twig
- Doctrine
- API

Version imprimable

[ Modifier le sommaire ]

Doctrine

Sommaire

API Platform

Installation

 composer require api

Utilisation

Le GraphQL de la version 1.1 passe par le schéma REST, et ne bénéficie donc pas du gain de performances attendu sans overfetching.

En bref, les routes d'API sont définies depuis les entités Doctrine.

Pour ajouter des fonctionnalités supplémentaires aux create/read/update/delete, il faut passer par des data providers^[3] ou des data persisters^[4], pour transformer les données, respectivement à l'affichage et à la sauvegarde.

Sécurité

Par défaut toutes les routes sont accessibles sans identification (selon security.yaml). Pour changer cela, on peut utiliser les Custom Doctrine ORM Extension^[5] :

class CurrentApiUserExtension implements QueryCollectionExtensionInterface, QueryItemExtensionInterface
{ ... }

Attributs

ApiResource

Définit les noms et méthodes REST (GET, POST...) des routes de l'API.

Exemple sur la V3^[6] :

#[ApiResource(
    operations: [
        new Get(),
        new GetCollection()
    ]
)]
class MyEntity...

Avec personnalisation de la vue OpenAPI :

#[ApiResource(
   operations: [
       new Get(),
       new GetCollection(),
   ],
   openapiContext: [
       'summary' => '',
       'tags' => ['Enums'],
   ]
)]

Idem sur la V2

#[ApiResource(
   collectionOperations: [
       'get' => [
           'openapiContext' => [
               'summary' => '',
               'tags' => ['Enums'],
           ],
       ],
   ],
   itemOperations: [
       'get' => [
           'openapiContext' => [
               'summary' => '',
               'tags' => ['Enums'],
           ],
       ],
   ],
)]

ApiProperty

Par exemple pour masquer un champ d'entité sur la route d'API :

#[ApiProperty(readable: false, writable: false, required: false, fetchable: false)]

MaxDepth

Définit le niveau de sérialisation d'un élément lié. Par exemple, si un client a plusieurs contrats et que ses contrats ont plusieurs produits, un MaxDepth(1) sur l'attribut client->contrat fera que la liste des clients comprendra tous les contrats mais pas leurs produits.

Évènements

API Platform ajoute plus d'une dizaine d'évènements donc les priorités sont définies dans EventPriorities^[7].

Par exemple, pour modifier un JSON POST envoyé, utiliser EventPriorities::PRE_DESERIALIZE.

L'évènement suivant POST_DESERIALIZE contient les objets instanciés à partir du JSON.

Triplet de bibliothèques

Installation

FOS REST

FOSRestBundle apporte des annotations pour créer des contrôleurs d'API^[8]. Installation :

composer require "friendsofsymfony/rest-bundle"

Puis dans config/packages/fos_rest.yaml :

fos_rest:
    view:
        view_response_listener:  true
    format_listener:
        rules:
            - { path: '^/',  prefer_extension: true, fallback_format: ~, priorities: [ 'html', '*/*'] }
            - { path: ^/api, prefer_extension: true, fallback_format: json, priorities: [ json ] }

Documentation

Toute API doit exposer sa documentation avec ses routes et leurs paramètres. NelmioApiDocBundle est un de générateur de documentation automatique à partir du code^[9], qui permet en plus de tester en ligne. En effet, pour éviter de tester les API en copiant-collant leurs chemins dans une commande cURL ou dans des logiciels plus complets comme Postman^[10], on peut installer une interface graphique ergonomique qui allie documentation et test en ligne :

    composer require "nelmio/api-doc-bundle"

Son URL se configure ensuite dans routes/nelmio_api_doc.yml :

app.swagger_ui:
    path: /api/doc
    methods: GET
    defaults: { _controller: nelmio_api_doc.controller.swagger_ui }

À ce stade l'URL /api/doc affiche juste un lien NelmioApiDocBundle. Mais si les contrôleurs d'API sont identifiés dans annotations.yaml (avec un préfixe "api"), on peut voir une liste automatique de toutes leurs routes.

Pour documenter /api/* sauf /api/doc, il faut préciser l'exception en regex dans packages/nelmio_api_doc.yaml :

nelmio_api_doc:
    areas:
        path_patterns:
            - ^/api/(?!/doc$)

Il faut vider le cache de Symfony à chaque modification de nelmio_api_doc.yaml.

Authentification

Pour tester depuis la documentation des routes nécessitant un token JWT, ajouter dans packages/nelmio_api_doc.yaml :

nelmio_api_doc:
    documentation:
        securityDefinitions:
            Bearer:
                type: apiKey
                description: 'Value: Bearer {jwt}'
                name: Authorization
                in: header
        security:
            - Bearer: []

Il devient alors possible de renseigner le token avant de tester.

{{remarque|Si par défaut (sans configuration) on voit juste un champ "JWT (http, Bearer)" non envoyé depuis l'API doc, ajouter le paragraphe suivant pour qu'il le soit :

        security:
            - JWT: []

Exemple

Dans un contrôleur, au-dessus de l'attribut #[Route] d'un CRUD :

use OpenApi\Attributes as OA;
...
    #[OA\Post(
        requestBody: new OA\RequestBody(
            required: true,
            content: [
                new OA\JsonContent(
                    examples: [
                        new OA\Examples('1', summary: 'By ID', value: '{ "myEntity": { "id": 1 }}'),
                        new OA\Examples('2', summary: 'By name', value: '{ "myEntity": { "name": "TEST" }}'),
                    ],
                    type: 'object',
                ),
            ],
        ),
        tags: ['MyEntities'],
        responses: [
            new OA\Response(
                response: Response::HTTP_OK,
                description: 'Returns myEntity information.',
                content: new OA\JsonContent(
                    properties: [
                        new OA\Property(
                            property: "id",
                            type: "integer",
                            example: 1,
                            nullable: true
                        ),
                        new OA\Property(
                            property: "name",
                            type: "string",
                            example: 'TEST',
                            nullable: true
                        ),
                    ]
                )
            ),
            new OA\Response(
                response: Response::HTTP_NOT_FOUND,
                description: 'Returns no myEntity.',
                content: new OA\JsonContent(
                    properties: [
                        new OA\Property(
                            property: "id",
                            type: "integer",
                            example: null,
                            nullable: true
                        ),
                    ]
                )
            )
        ]
    )]

Sérialiseur

Enfin pour la sérialisation, on distingue plusieurs solutions :

symfony/serializer, qui donne des contrôleurs extends AbstractFOSRestController et des méthodes aux annotations @Rest\Post()^[11].
jms/serializer-bundle, avec des contrôleurs extends RestController et des méthodes aux annotations @ApiDoc().
Le service fos_rest.service.serializer.

symfony/serializer

    composer require "symfony/serializer"

jms/serializer-bundle

    composer require "jms/serializer-bundle"

Utilisation

Maintenant /api/doc affiche les méthodes des différents contrôleurs API. Voici un exemple :

<?php

namespace App\Controller;

use FOS\RestBundle\Controller\AbstractFOSRestController;
use FOS\RestBundle\View\View;
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\Routing\Annotation\Route;

class APIController extends AbstractFOSRestController
{
    #[Route('/api/test', methods: ['GET'])]
    public function testAction(Request $request): View
    {
        return View::create('ok');
    }
}

Dans PHP < 8

...
    /**
     * @Route("/api/test", methods={"GET"})
     */
    public function testAction(Request $request): View
...
}

Maintenant dans /api/doc, cliquer sur /api/test, puis "Ty it out" pour exécuter la méthode de test.

Sécurité

Une API étant stateless, l'authentification est assurée à chaque requête, par l'envoi par le client d'un token JSON Web Token (JWT) dans l'en-tête HTTP (clé Authorization). Côté serveur, on transforme ensuite le JWT reçu en objet utilisateur pour accéder à l'identité du client au sein du code. Ceci est fait en configurant security.yaml, pour qu'un évènement firewall appelle automatiquement un guard authenticator^[12] :

composer require "symfony/security-bundle"

security:
    firewalls:
        main:
            guard:
                authenticators:
                    - App\Security\TokenAuthenticator

Manipuler les JWT

Pour décrypter le JWT :

use Lexik\Bundle\JWTAuthenticationBundle\Encoder\JWTEncoderInterface;
...
    public function __construct(
        private readonly JWTEncoderInterface $jwtEncoder,
    ) {
    }

    public function decodeJwt(string $jwt): array
    {
        return $this->jwtEncoder->decode($jwt):
    }

Résultat minimum :

array:6 [
  "iat" => 1724677672
  "exp" => 1724764072
  "roles" => array:1 [
    0 => "ROLE_INACTIF"
  ]
  "username" => "test"
]

Si on n'a pas besoin de vérifier le JWT (validité, expiration et signature modifiée par un pirate), on peut se passer de Lexik ainsi :

    private function decodeJwt(string $jwt): array|bool|null
    {
        $tokenParts = explode('.', $jwt);
        if (empty($tokenParts[1])) {
            return [];
        }

        $tokenPayload = base64_decode($tokenParts[1]);

        return json_decode($tokenPayload, true);
    }

Test

Pour tester en shell :

TOKEN=123
curl -H 'Accept: application/json' -H "Authorization: Bearer ${TOKEN}" http://localhost

Références

[1] ttps://api-platform.com/

[2] ttps://api-platform.com/docs/core/content-negotiation/

[3] ttps://api-platform.com/docs/core/data-providers/

[4] ttps://api-platform.com/docs/core/data-persisters/

[5] ttps://api-platform.com/docs/core/extensions/#custom-doctrine-orm-extension

[6] ttps://api-platform.com/docs/core/operations/

[7] ttps://api-platform.com/docs/core/events/

[8] ttps://github.com/FriendsOfSymfony/FOSRestBundle

[9] ttps://github.com/nelmio/NelmioApiDocBundle

[10] ttps://www.postman.com/

[11] ttps://www.thinktocode.com/2018/03/26/symfony-4-rest-api-part-1-fosrestbundle/

[12] ttps://symfony.com/doc/current/security/guard_authentication.html

[1]

[2]

[3]

[4]

[5]

[6]

[7]

[8]

[9]

[10]

[11]

[12]