Dans le développement d’une API, nous sommes tous confrontés au même défi : maintenir la cohérence entre la documentation et le code.

Qui n’a jamais perdu des heures à débugger une erreur parce que le champ user_id était devenu userId dans le code, mais pas dans la documentation ? C’est ce qu’on appelle le “drift”. À mesure que le projet évolue, le code change, mais la documentation (OpenAPI, Wiki, Postman) traîne souvent la patte, devenant une source d’erreurs plutôt qu’une aide.

Et si la solution n’était pas de mettre à jour manuellement notre code pour coller à la doc, mais de générer automatiquement notre code à partir de la doc ? C’est ici qu’intervient Jane.

Découvrir Jane

En deux mots : Jane est une suite de librairies PHP dont la mission est de générer du code de qualité à partir de vos spécifications JSON Schema ou OpenAPI.

Si l’on devait résumer son rôle dans une API moderne, Jane agit comme le “traducteur automatique” entre vos contrats d’interface (vos spécifications .yaml ou .json) et votre code PHP. Au lieu d’écrire manuellement vos classes, vos validateurs et vos clients HTTP — une tâche répétitive et sujette à l’erreur humaine — Jane les fabrique pour vous.

Concrètement, Jane analyse votre schéma et produit :

• Des Modèles (DTO) : Des classes PHP simples (POPO - Plain Old PHP Objects) strictement typées qui représentent vos données ;
• Des Normalizers : Toute la logique nécessaire pour transformer ces objets en JSON et inversement, en s’appuyant sur le composant symfony/serializer ;
• Un Client HTTP complet : (dans le cas du composant OpenAPI) Une implémentation prête à l’emploi (compatible PSR-18) pour consommer l’API, gérant les requêtes, les réponses et même les exceptions définies dans votre spec.

L’atout majeur de Jane n’est pas seulement le gain de temps, c’est la garantie de conformité. Puisque le code est généré directement depuis la source de vérité (le schéma), il est impossible d’avoir une divergence (“drift”) entre ce que votre documentation prétend faire et ce que votre code fait réellement. Si le schéma change, vous régénérez le code, et le tour est joué.

Voyons un projet d’exemple

Pour passer de la théorie à la pratique, nous allons construire un cas d’usage classique : un tunnel d’achat e-commerce.

Nous allons simuler la transformation d’un panier en une commande validée. Pour cela, nous découpons la logique en deux micro-services distincts :

1. Le service Panier : Il matérialise l’état d’attente avant la commande. C’est lui qui mémorise les articles choisis au fur et à mesure que le client parcourt le site, avant qu’il ne décide (ou non) de passer à l’achat ;
2. Le service Commande : Il gère la finalisation de la vente et la collecte des informations client.

Ce scénario nous permettra d’explorer des cas concrets :

• Côté Panier, nous utiliserons des UUID pour récupérer le contenu du panier ;
• Côté Commande, nous mettrons en place une validation stricte des données (regex pour le téléphone, énumération pour le pays) lors de la transformation du panier en commande, ainsi qu’un endpoint pour les codes promo.

Voyons maintenant comment formaliser tout cela dans nos contrats d’API.

Créer nos micro-services (1 / 2) : Panier

Commençons par le service le plus simple : le Panier.

Ici, nous prenons le parti du Design First : avant d’écrire la moindre ligne de PHP, nous allons figer la structure de nos échanges dans un fichier cart.yaml.

Pour ce service, le besoin est basique : nous voulons pouvoir récupérer un panier via son identifiant unique. Voici notre définition en OpenAPI 3.0.3 :

openapi: 3.0.3
info:
  title: 'Service Panier'
  version: 1.0.0
paths:
  /carts/{id}:
    get:
      summary: 'Récupérer un panier'
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: 'Le panier trouvé'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Cart'
components:
  schemas:
    Cart:
      type: object
      properties:
        id:
          type: string
          format: uuid
        items:
          type: array
          items:
            type: string # simplifié pour l'exemple

Ce qu’il faut retenir ici

L’utilisation du format uuid sur l’identifiant (id) n’est pas anodine. Jane exploite cette information pour enrichir le code généré avec des règles de validation strictes, garantissant que la donnée n’est pas une simple chaîne de caractères mais bien un UUID valide.

Nous avons posé les bases du Panier. Attaquons-nous maintenant au second morceau du puzzle, qui va nous demander un peu plus de rigueur : le service Commande.

Créer nos micro-services (2 / 2) : Commande

Passons maintenant aux choses sérieuses avec le service Commande. Si le Panier était une simple lecture, la Commande implique de recevoir et valider des données utilisateur critiques.

C’est l’occasion idéale pour définir des règles strictes directement dans notre fichier order.yaml. Nous allons déclarer deux routes :

1. Une route de création de commande, qui valide l’adresse et le téléphone, données indispensables pour assurer la livraison ;
2. Une route pour appliquer un code de réduction à une commande (qui impactera le prix).

Voici à quoi ressemble notre contrat :

openapi: 3.0.3
info:
  title: 'Service Commande'
  version: 1.0.0
paths:
  /orders:
    post:
      summary: 'Créer une commande à partir d un panier'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrderInput'
      responses:
        '201':
          description: 'Commande créée'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'

/orders/{id}/discount:
    post:
      summary: 'Ajouter un code promo'
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                code:
                  type: string
      responses:
        '200':
          description: 'Code promo appliqué'

components:
  schemas:
    OrderInput:
      type: object
      required: ['cartId', 'customer']
      properties:
        cartId:
          type: string
          format: uuid
        customer:
          $ref: '#/components/schemas/CustomerAddress'

    CustomerAddress:
      type: object
      required: ['firstName', 'lastName', 'phoneNumber', 'countryCode']
      properties:
        firstName:
          type: string
        lastName:
          type: string
        phoneNumber:
          type: string
          pattern: '^\+33[1-9]\d{8}$' # Validation Regex pour numéros français
          description: 'Format: +33xxxxxxxxx'
        countryCode:
          type: string
          enum: ['FR', 'BE', 'LU'] # Limitation par énumération

    Order:
      type: object
      properties:
        id:
          type: string
          format: uuid
        status:
          type: string
          enum: ['pending', 'paid', 'shipped']
        price:
          type: number
          description: 'Prix final après réduction éventuelle'

Pourquoi aller aussi loin dans la spec ?

Regardez bien le schéma CustomerAddress. Nous n’avons pas seulement défini des chaînes de caractères, nous avons imposé des contraintes métiers :

• pattern : Le champ phoneNumber doit correspondre à une regex précise (+33…).
• enum : Le champ countryCode ne peut être qu’une valeur parmi une liste définie (France, Belgique, Luxembourg).

Au lieu de coder ces validations “à la main” dans chaque contrôleur PHP, nous les déclarons une seule fois dans le contrat. Jane se chargera de traduire ces contraintes dans le code généré, garantissant que si une donnée ne respecte pas la spec, elle ne passera pas.

Nos contrats sont prêts. Il est temps de passer au PHP.

Configuration de Jane pour le projet exemple

Nos spécifications OpenAPI sont prêtes (cart.yaml et order.yaml). Il faut maintenant expliquer à Jane comment les transformer en code PHP.

Cela se passe via un fichier de configuration, généralement nommé .jane-openapi.php à la racine du projet.

Pour gérer nos deux micro-services (Panier et Commande) sans mélanger leur code, nous utilisons l’option mapping. Elle permet de définir des règles de génération spécifiques pour chaque fichier OpenAPI au sein d’une seule et même configuration.

Voici à quoi ressemble notre fichier .jane-openapi.php:

<?php

return [
    'mapping' => [
        __DIR__ . '/cart.yaml' => [
            'namespace' => 'App\Generated\Cart',
            'directory' => __DIR__ . '/generated/Cart',
        ],
        __DIR__ . '/order.yaml' => [
            'namespace' => 'App\Generated\Order',
            'directory' => __DIR__ . '/generated/Order',
        ],
    ],
    ‘validation’ => true,
];

Les options disponibles

Déchiffrons ensemble cette configuration :

• mapping : C’est la clé maîtresse qui nous permet d’associer chaque fichier de spécification (la clé du sous-tableau, ici le chemin vers cart.yaml ou order.yaml) à sa propre configuration.
• namespace : C’est ici que l’organisation se joue. En donnant des namespaces différents (App\Generated\Cart vs App\Generated\Order), nous isolons complètement les domaines. Si un modèle s’appelle Error dans les deux services, il n’y aura aucun conflit de nom de classe dans notre projet.
• directory : Le dossier de destination où le code PHP généré pour chaque service va être écrit.
• validation : C’est une option capitale. En la passant à true, nous demandons à Jane de traduire les contraintes du schéma OpenAPI (comme minimum: 1, required, email) en métadonnées de Symfony Validator. C’est le socle qui nous permettra de garantir la robustesse des données sans avoir à réécrire manuellement les règles métiers en PHP. Nous verrons plus loin à quel point cela nous simplifie la vie.

Avec cette structure, Jane va itérer sur chaque entrée du mapping et produire automatiquement deux clients HTTP (compatibles PSR-18) distincts et autonomes.

Et les erreurs ? Standardisation et gestion avec Jane

Gérer le “happy path” (code 200), c’est facile. Mais dans la vraie vie, une API échoue : validation invalide (400), accès refusé (403) ou crash serveur (500).

Si nous laissons Jane deviner, elle lèvera des exceptions génériques HTTP. Mais nous pouvons faire mieux : nous pouvons uniformiser le format de nos erreurs pour que notre SDK PHP renvoie des objets structurés, faciles à manipuler dans un try/catch.

Définir un schéma d’erreur standard

Dans nos fichiers OpenAPI (cart.yaml et order.yaml), nous allons ajouter une définition réutilisable dans la section components. Cela permet d’avoir un format unique (par exemple : un message et un code) pour toutes nos erreurs.

Ajoutons ceci à la fin de nos fichiers YAML :

components:
  schemas:
    # ... nos autres modèles (Cart, Product...)

    # Notre modèle d'erreur standardisé
    Error:
      type: object
      required:
        - message
        - code
      properties:
        message:
          type: string
          description: Le message d'erreur pour le développeur
        code:
          type: integer
          description: Un code d'erreur interne spécifique

Référencer ce schéma dans les endpoints

Maintenant que le modèle Error existe, nous devons dire à chaque endpoint : “Si nous renvoyons une 400, 403 ou 500, le corps de la réponse respectera ce schéma”.

Reprenons l’exemple de l’ajout d’un code de réduction sur une commande:

paths:
  /orders/{id}/discount:
    post:
      summary: 'Ajouter un code promo'
      # ... (requestBody, etc)
      responses:
        '200':
          description: 'Code promo appliqué'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'

        # Gestion des erreurs standardisée
        '400':
          description: 'Données invalides (ex: code non trouvé)'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Action non autorisée
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Commande introuvable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Erreur serveur
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

Ce que Jane va générer pour nous

C’est ici que la magie opère. Lors de la génération, Jane va détecter ces configurations et produire deux choses très utiles :

1. Un POPO Error : Une classe PHP classique (App\Generated\Order\Model\Error) avec ses getters et setters.
2. Des Exceptions spécifiques : Pour l’endpoint ci-dessus, Jane va générer des exceptions comme AddDiscountBadRequestException ou AddDiscountNotFoundException.

Ces exceptions auront une méthode getError() qui retournera… notre instance du modèle Error remplie avec les données de l’API !

Cela permet d’écrire un code client très propre :

try {
    $api->addDiscount('C17891', new OrdersIdDiscountPostBody('NOEL2025'));
} catch (AddDiscountBadRequestException|AddDiscountNotFoundException $e) {
    // On récupère notre objet Error proprement
    $errorModel = $e->getResponse();
    echo "Erreur fonctionnelle : " . $errorModel->getMessage();
} catch (ClientExceptionInterface $e) {
    // Erreur réseau ou autre
}

En standardisant vos retours d’erreurs dans l’OpenAPI, vous garantissez que le code PHP généré est prévisible et facile à utiliser pour les développeurs qui consommeront votre SDK.

Lancer la génération du code !

C’est ici que la magie opère. Fini d’écrire des DTOs, des clients HTTP et des exceptions à la main. Jane va faire tout ce travail fastidieux pour nous.

Dans votre terminal, à la racine du projet, lancez simplement :

vendor/bin/jane-openapi generate --config-file .jane-openapi.php

Jane va lire le fichier .jane-openapi.php, détecter notre mapping et générer les fichiers correspondants. Si vous allez voir dans votre dossier generated/, nous avons deux nouveaux dossiers qui sont apparus : Cart et Order.

Une étape indispensable : l’autoloader

Avoir les fichiers PHP, c’est bien, mais pouvoir les utiliser, c’est mieux ! Comme ce sont de nouvelles classes dans un nouveau dossier, Composer ne les connaît pas encore.

Pour que Composer puisse charger ces nouvelles classes, nous devons mettre à jour le composer.json. Plutôt que de déclarer chaque service un par un, allons au plus simple : nous allons faire pointer le namespace parent App\Generated\ directement vers le dossier generated/.

Ouvrez votre composer.json et ajoutez ces lignes dans la section autoload :

"autoload": {
    "psr-4": {
        "App\\": "src/",
        "App\\Generated\\": "generated/"
    }
},

Ensuite, pour que cette modification soit prise en compte, régénérez l’autoloader :

composer dump-autoload

C’est tout ! Votre projet est maintenant prêt à utiliser les librairies générées.

Que contient ce dossier generated ?

Si vous êtes curieux (et vous devriez l’être), jetez un œil à l’intérieur de generated/Cart ou generated/Order. Vous y trouverez une structure très organisée :

generated/
├── Order
│   ├── Client.php
│   ├── Endpoint
│   ├── Exception
│   ├── Model
│   ├── Normalizer
│   ├── Runtime
│   │   ├── Client
│   │   └── Normalizer
│   └── Validator
└── Cart
    ├── Same file structure as Order
    └── ...

• Client.php : Votre point d’entrée principal. C’est la classe qui contient toutes les méthodes comme createOrder(), addDiscount(), etc.
• Endpoint/ : Chaque opération définie dans votre schéma OpenAPI (comme GET /carts/{id}) possède ici sa propre classe dédiée. C’est elle qui orchestre l’appel API : elle sait quelle méthode HTTP utiliser, quel corps de requête envoyer, comment transformer la réponse brute en un objet de votre Model et comment gérer les exceptions selon le code de retour.
• Exception/ : C’est ici que se trouvent nos erreurs typées (AddDiscountBadRequestException, etc.) basées sur les codes HTTP et nos schémas d’erreurs.
• Model/ : Vos POPO (Plain Old PHP Objects). Ce sont les classes Cart, Order, OrderInput, etc. Elles contiennent simplement des propriétés, des getters et des setters.
• Normalizer/ : C’est le cœur de Jane (basé sur le composant Serializer de Symfony). Ces classes savent comment transformer vos objets en JSON et inversement.
• Runtime/ : C’est la salle des machines. Ce dossier contient le code “support” nécessaire au fonctionnement global du SDK généré (configuration du client, normalizers de base). Ce sont des composants techniques qui font le lien entre votre code généré et les librairies tierces (comme le client HTTP PSR-18).
• Validator/ : C’est la particularité liée à notre option "validation": true. Jane génère des classes de contraintes spécifiques (ex: OrderInputConstraint).
• Détail technique : Ces classes étendent Compound de Symfony Validator. Elles regroupent toutes les règles définies dans votre OpenAPI (Required, Email, Regex etc.) en une seule classe appelable. Cela garde vos modèles propres tout en garantissant une validation stricte.

Utilisation pratique : intégrer les modèles Jane dans votre code

Maintenant que nos classes sont générées, comment les utiliser concrètement ?

Jane brille par sa rigueur : elle sécurise les échanges via ses Normalizers et force l’utilisation d’objets typés.

La validation automatique

L’un des atouts de Jane est qu’elle intègre la validation directement dans le processus de sérialisation et de désérialisation.

Cela signifie que le contrôle des données est actif dans les deux sens :

1. En entrée (Désérialisation) : Vous ne pouvez pas créer un objet PHP invalide à partir d’un JSON reçu.
2. En sortie (Sérialisation) : Vous ne pouvez pas générer un JSON invalide à partir d’un objet PHP (par exemple, si vous avez oublié de remplir un champ obligatoire avant de renvoyer la réponse).

Vous n’avez donc plus besoin d’appeler le validateur manuellement. Regardez le code généré dans le Normalizer (ici OrdersIdDiscountPostBodyNormalizer) : il vérifie les contraintes pendant la transformation.

Si vous utilisez le Serializer de Symfony dans votre contrôleur, la validation est implicite :

namespace App\Controller;

use App\Generated\Order\Model\OrdersIdDiscountPostBody; // Le DTO généré
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Serializer\SerializerInterface;
use Symfony\Component\Serializer\Exception\ValidationFailedException;

class OrderController extends AbstractController
{
    public function addDiscount(Request $request, SerializerInterface $serializer)
    {
        try {
            // C'est ici que la magie opère :
            // Jane désérialise ET valide en même temps.
            // Si le JSON est invalide (code manquant, trop court...), une exception est levée.
            /** @var OrdersIdDiscountPostBody $body */
            $body = $serializer->deserialize(
                $request->getContent(),
                OrdersIdDiscountPostBody::class,
                'json'
            );

        } catch (ValidationFailedException $e) {
            // On récupère les violations pour répondre une 400 propre via la constante Symfony
            return $this->json($e->getViolations(), Response::HTTP_BAD_REQUEST);
        }

        // Si on arrive ici, $body est un objet valide et typé !
        $code = $body->getCode();
        // ... traitement métier
    }
}

Le gain ? Votre code métier ne manipule jamais de données “sales”. Et inversement, vous avez la certitude absolue que vos réponses API respectent toujours le contrat défini dans votre fichier YAML.

Gérer les erreurs (Exceptions typées)

C’est ici que notre travail sur les schémas d’erreurs 400 / 404 / 500 porte ses fruits. Jane a généré des exceptions spécifiques pour chaque cas d’erreur documenté.

Fini les vérifications manuelles du status code, place aux try/catch explicites :

use App\Generated\Order\Exception\AddDiscountBadRequestException;
use App\Generated\Order\Exception\AddDiscountNotFoundException;
use App\Generated\Order\Model\OrdersIdDiscountPostBody;

try {
    $payload = new OrdersIdDiscountPostBody();
    $payload->setCode('INVALID');

    $apiClient->addDiscount('order-12345', $payload);

} catch (AddDiscountBadRequestException $e) {
    // C'est une 400 spécifique à cette route (Response::HTTP_BAD_REQUEST)
    // On récupère notre objet Error structuré défini dans l'OpenAPI
    $errorModel = $e->getError();

    // Affiche : "Code promo invalide ou expiré"
    $logger->warning($errorModel->getMessage());

} catch (AddDiscountNotFoundException $e) {
    // C'est une 404 spécifique (Commande ou code de réduction introuvable)
    // ...
} catch (\Exception $e) {
    // Erreur réseau ou 500 générique
}

Communication inter-services : Quand le service Commande appelle le service Panier

Dans une architecture microservices, la communication synchrone (HTTP) est souvent le talon d’Achille. On se retrouve vite avec des appels curl ou Guzzle éparpillés, des tableaux associatifs non typés et, surtout, une confiance aveugle envers le service appelé.

Maintenant, nous allons voir comment Jane sécurise l’échange entre notre service Commande (le consommateur) et le service Panier (le producteur).

Le contrat comme dépendance : Réutiliser le schéma OpenAPI

Au lieu de redéfinir manuellement une classe PanierDTO dans le service Commande (qui finirait inévitablement par diverger de la réalité), nous utilisons directement la définition OpenAPI du service Panier.

Concrètement, cela signifie que le fichier openapi.yaml du service Panier devient une “dépendance” du service Commande.

• Configuration Jane : Dans le service Commande, nous configurons Jane pour pointer vers ce fichier (via une URL, un submodule git, …).
• Single Source of Truth : Si l’équipe Panier met à jour son modèle (par exemple, en ajoutant un champ promoCode), le service Commande le saura dès la prochaine régénération du code.

Génération d’un Client HTTP typé (SDK interne)

C’est une des fonctionnalités clé de Jane pour la communication inter-services. En plus des modèles (DTOs), Jane a généré un Client HTTP complet prêt à l’emploi (compatible PSR-18).

Pour l’utiliser, on va instancier le client via sa méthode statique create() :

use App\Generated\Panier\Client;

$panierClient = Client::create();
$panier = $panierClient->getPanier($uuid);

// $panier est une instance de la classe \App\Generated\Panier\Model\Panier
// L'IDE connaît toutes les propriétés :
$total = $panier->getTotal();
foreach ($panier->getItems() as $item) {
    // ...
}

Nous manipulons des objets PHP natifs, typés, générés spécifiquement pour cette interaction.

Validation automatique de la réponse

Que se passe-t-il si le service Panier a un bug et renvoie un prix sous forme de chaîne de caractères 10,50€ au lieu d’un nombre 10.50, ou s’il manque un champ obligatoire ?

Avec un client HTTP manuel, votre code planterait probablement plus loin, de manière obscure (Call to member function on null ou erreur de calcul), ou pire, corromprait vos données silencieusement.

Avec le client généré par Jane :

• Le client valide automatiquement la réponse HTTP reçue par rapport au schéma OpenAPI ;
• Si la réponse ne respecte pas le contrat (type incorrect, champ manquant), Jane lève immédiatement une UnexpectedValueException ou une InvalidResponseException ;
• Fail Fast : L’application s’arrête net à la frontière du service, empêchant des données invalides de polluer votre logique métier de commande.

En résumé, Jane transforme un appel HTTP incertain en un appel de méthode PHP sûr et typé.

Validation stricte dans les tests

Au lieu de charger vos données de test et ne jamais vérifier leur intégrité, passez-les dans la moulinette de Jane.

Si votre donnée ne correspond plus à la réalité de l’API (changement de type, champ manquant), Jane le détecte immédiatement.

// 1. On charge la donnée brute (ici on prends un JSON en exemple
// mais un endpoint API fonctionnera pareil
$data = json_decode(file_get_contents('panier_fixture.json'), true);

// 2. On demande à Jane de créer l'objet.
// C'est ici que la magie opère : Jane vérifie TOUT le contrat via la validation
// dans le Normalizer généré
try {
    $panier = $serializer->denormalize($data, Panier::class);
} catch (Exception $e) {
    // Le test échoue immédiatement si le JSON est périmé !
    $this->fail('Vos données de test ne respectent plus le contrat OpenAPI : ' . $e->getMessage());
}

// 3. On utilise un objet PHP valide pour configurer le mock
// ou autre test que vous voudriez faire
$mockService->method('getPanier')->willReturn($panier);

Pourquoi c’est puissant ?

Cela transforme vos tests unitaires en tests de contrat légers. Vous n’avez plus peur que vos tests “passent au vert” alors qu’ils utilisent des données obsolètes qui feront planter la production.

Évolution et versioning : Faire évoluer votre API sans tout casser

Une API n’est jamais figée. Elle vit, elle change, elle s’étend. Le cauchemar de tout développeur est de déployer une mise à jour qui casse la communication entre les services. Avec Jane, l’impact d’une modification du contrat OpenAPI devient immédiatement visible dans votre code PHP.

Ajout d’un champ optionnel (Non-breaking change)

C’est le scénario idéal. Vous ajoutez, par exemple, une description facultative à votre objet Commande.

• Dans l’OpenAPI : Vous ajoutez le champ sans le marquer comme required.
• Après régénération Jane : Votre classe Commande gagne une propriété protected ?string $description = null; ainsi que ses getters et setters.
• Impact : Nul. Votre code existant continue de fonctionner parfaitement car le constructeur reste compatible (le nouveau champ est initialisé à null par défaut). C’est une évolution en douceur.

Ajout d’un champ obligatoire (Breaking change)

C’est ici que Jane vous sauve la mise. Imaginons que le service Panier exige désormais un customerId pour chaque création de panier.

• Dans l’OpenAPI : Le champ customerId est ajouté à la liste required.
• Après régénération Jane : La signature du constructeur de la classe Panier change radicalement.
  • Avant : public function __construct(string $uuid)
  • Après : public function __construct(string $uuid, string $customerId)
• Impact : Immédiat et visible. Partout dans votre code où vous instanciez un Panier sans ce nouvel argument, votre code ne fonctionne plus. Votre IDE (PhpStorm, VSCode) surligne les erreurs en rouge avant même que vous ne lanciez le moindre test.

Note clé : Jane transforme une erreur de “runtime” (qui arriverait en production) en une erreur de “compile-time” (qui arrive sur votre machine).

Régénération et impact sur le code : La boucle de sécurité

Le workflow de mise à jour devient alors très sécurisant :

1. Mise à jour du contrat : Vous récupérez la nouvelle version de openapi.yaml.
2. Régénération : Vous lancez la génération du code Jane.
3. Analyse d’impact : Vous lancez l’analyse statique (PHPStan, Psalm) ou simplement vos tests.
4. Correction : Jane vous a forcé à voir tous les endroits du code impactés par le changement. Vous ne pouvez pas “oublier” de traiter le nouveau champ obligatoire.

En résumé, Jane agit comme un révélateur de dette technique immédiat lors des mises à jour d’API.

Conclusion : Pourquoi passer à l’approche “Contract-First” avec Jane ?

Au fil de cet article, nous avons vu que Jane n’est pas simplement un générateur de code, c’est un changement de paradigme dans la façon de concevoir la communication entre vos services. En plaçant le schéma OpenAPI au centre du jeu, vous gagnez sur quatre tableaux majeurs :

Type Safety : L’armure de votre code

Fini les array mystérieux qui circulent d’un service à l’autre. Avec Jane, chaque donnée entrante ou sortante est encapsulée dans un objet PHP fortement typé.

Vous savez exactement ce que vous manipulez : des entiers sont des int, des dates sont des \DateTime. PHPStan et votre IDE vous remercient, et votre code devient auto-documenté par sa structure même.

Documentation Vivante

Souvent, la documentation est le parent pauvre du projet : écrite au début, jamais mise à jour, et finalement trompeuse.

Ici, la spécification OpenAPI est votre Source de Vérité. Puisque c’est elle qui génère le code qui tourne en production, elle est de facto toujours à jour.

Couplée à des outils de visualisation comme SwaggerUI ou ReDoc, cette documentation devient interactive et fiable pour toutes les équipes (frontend, mobile, partenaires). Ce que vous voyez dans la doc est exactement ce que le code attend.

Moins de Bugs en Production

En transformant les erreurs de runtime (données mal formées, champs manquants) en erreurs de “compile-time” (le code généré change, l’IDE signale l’erreur), vous capturez les bugs le plus tôt possible.

La validation automatique des réponses agit comme un filet de sécurité : aucune donnée corrompue ne peut pénétrer silencieusement dans votre système pour causer des erreurs en cascade plus loin.

Une DX retrouvée

C’est peut-être le point le plus important au quotidien. Plus besoin de faire des allers-retours incessants entre le code et une documentation PDF externe.

• L’autocomplétion de l’IDE fonctionne instantanément.
• Les refactorings sont sûrs.
• Les tests sont plus simples à écrire et plus robustes.

Performance accrue

Au-delà de la sécurité et du confort, le gain de performance est significatif. Le code généré par Jane étant spécifique à vos modèles, il est beaucoup plus performant que l’utilisation générique de l’ObjectNormalizer du Serializer de Symfony. En évitant d’utiliser la Reflection lors de l’exécution de votre code, vos applications consomment moins de ressources et répondent plus vite.

Le mot de la fin : Arrêtez d’écrire vos clients HTTP et vos DTOs à la main. Laissez Jane faire, de manière optimisée, le travail répétitif et concentrez-vous sur ce qui a de la valeur : votre logique métier.

Récemment vous avez peut-être entendu parler de PIE, un nouveau binaire pour PHP. PIE c’est le diminutif de “PHP Installer for Extensions” et c’est donc le descendant de PECL.

Pourquoi PIE ?

PHP, né en 1995, célèbre cette année ses 30 ans d’existence 🎉. Durant ces trois décennies, l’écosystème de ce langage s’est considérablement enrichi avec l’émergence d’outils devenus indispensables aux développeurs.

En 1999, PEAR (PHP Extension and Application Repository) a posé les bases de la réutilisation de code en servant de premier gestionnaire de bibliothèques standardisés.

Puis en 2003, PECL (PHP Extension Community Library) a étendu les capacités du langage en facilitant l’intégration d’extensions compilées pour traiter efficacement des données complexes comme le XML ou les chaînes de caractères multioctets (mbstring).

La véritable révolution est survenue en 2012 avec Composer, qui a transformé radicalement la gestion des dépendances dans les projets PHP.

Plus récemment, après plus de 25 ans d’existence de PECL, PIE (PHP Install Extensions) a fait son apparition comme alternative prometteuse. Encore en phase de développement, cette initiative, lancée par la PHP Foundation, apporte une approche moderne et simplifiée pour l’installation et la gestion des extensions PHP. Son utilisation actuelle, bien que limitée par sa maturité, s’illustre déjà par sa simplicité que nous allons voir ensemble.

D’ici quelque temps, vous installerez vos extensions PHP de cette façon.

Mise en place

Avant de commencer l’installation de PIE, vous devez préparer votre environnement avec quelques outils de développement essentiels. Utilisez la commande suivante pour installer les pré-requis nécessaires (pour linux) :

sudo apt install git autoconf automake libtool m4 make gcc

Puis l’installation de l’outil est remarquablement simple, ne nécessitant qu’une seule ligne de commande (oui c’est un PHAR, comme Composer ou Castor) :

sudo curl -L --output /usr/local/bin/pie https://github.com/php/pie/releases/latest/download/pie.phar && sudo chmod +x /usr/local/bin/pie

Cette méthode d’installation est adaptée pour les distributions Linux. Si vous utilisez autre chose, vous pouvez voir dans la documentation de PIE pour les méthodes alternatives d’installation

Et voilà, avec ces deux commandes vous avez l’outil installé dans sa dernière version et prêt à être utilisé ! 🎉

Première utilisation

Après l’installation, vous pouvez rapidement enrichir votre environnement PHP avec de nouvelles extensions. Commençons par un exemple pratique. Supposons que vous souhaitiez ajouter l’extension uuid pour gérer des identifiants uniques dans votre projet, alors il vous suffira de faire la commande suivante :

pie install pecl/uuid

Selon votre niveau de privilèges sur ce système Linux, le programme pourrait vous demander d’utiliser la commande sudo pour obtenir les droits nécessaires à l’installation de l’extension demandée. Suite à cette installation, l’extension sera disponible globalement sur l’ensemble du système et non limitée au projet actuel. Vous pouvez découvrir toutes les extensions disponibles sur packagist.

Diverses commandes

L’outil propose une panoplie de commandes pour gérer vos extensions PHP. Par exemple, pour supprimer une extension précédemment installée :

pie uninstall pecl/uuid

Ou encore pour lister les extensions installées :

pie show

Et enfin pour afficher les détails d’une extension en particulier :

pie info pecl/uuid

Gérer plusieurs dépôts d’extensions

PIE ne se limite pas aux extensions disponibles sur Packagist. L’outil offre une grande flexibilité en permettant l’installation d’extensions provenant de diverses sources : dépôts GitHub, archives locales, ou même des extensions développées en interne.

pie repository:add path /path/to/your/local/extension
pie repository:add vcs https://github.com/youruser/yourextension
pie repository:add composer https://repo.packagist.com/your-private-packagist/

Et vous retrouverez aussi les commandes pour supprimer un dépôt :

pie repository:remove /path/to/your/local/extension

Ou juste lister les dépôts que vous avez ajoutés :

pie repository:list

Comme l’outil utilise symfony/console, vous pouvez avoir de l’autocompletion :

pie completion | sudo tee /etc/bash_completion.d/pie

Conclusion

Lors de la relecture de cet article, une question m’a été posée : pourquoi ne pas utiliser APT ou d’autres gestionnaires de paquets (comme Brew, Yum, etc.) à la place ? À mon avis, PIE offre un avantage considérable : l’accès à une bibliothèque d’extensions PHP beaucoup plus vaste. Les gestionnaires de paquets traditionnels exigent des développeurs qu’ils créent et compilent leur package pour différentes architectures, ce qui représente un travail conséquent. En revanche, PIE simplifie radicalement ce processus. Il récupère automatiquement le code source et les dépendances de l’extension, puis la compile spécifiquement pour l’appareil où il est installé. Pour les développeurs, la procédure est allégée : il leur suffit d’enregistrer leur extension sur Packagist pour la rendre disponible à tous les utilisateurs de PIE.

Tout de même, PIE démontre déjà des fonctionnalités solides et intuitives pour la gestion des extensions PHP. Bien qu’encore en développement, l’outil offre une base prometteuse qui simplifie l’installation et la gestion des extensions.

Nous sommes impatients de voir comment la communauté PHP va adopter et faire évoluer PIE dans les mois et années à venir.

Pour plus d’informations n’hésitez pas à consulter le repository github de l’outil. Ou suivre le blog de la PHP Foundation !

We recently attended a talk about lazy-loading by Nicolas Grekas and it inspired me this blogpost!

We can find lazy-loading in all modern PHP applications, in ORMs, for example. But is there more usage of lazy-loading?

What is lazy-loading?

In short: lazy-loading consists of delaying load or initialization of resources or objects until they’re actually needed. It’s something you will never see directly, the whole objective of lazy-loading is to be invisible so you can use your applications the way you always do.

And behind this invisible thing, we will give you something that will act as the object you want but will only load its content when required.

We can see two main pros about using lazy-loading:

• It will save memory and CPU until we load the data
• It may never be called since you sometimes load nested objects that you don’t need…

What is lazy-loading? Martin Fowler, in his book “Patterns of Enterprise Application Architecture”, explains this pattern very well. There are 4 types of lazy-loading patterns. Each of them have pros & cons:

• Lazy initialization, your object contains a null property and whenever you need that property, it will initialize it. In that case, your object needs to be aware that it is lazy-loaded;
• Value holders, it’s an object that is responsible for initializing another object whenever you need it. It will require you to write a different class but the base class will stays the same;
• Virtual proxy is an object that is using the same interface (methods) that is used in the base object and whenever you use one of those methods, it will instantiate the base object and delegate to it;
• Ghost objects are objects that are to be loaded in a partial state. It may initially only contain the object’s identifier, but it loads its own data the first time one of its properties or methods are accessed.

In PHP we have some libraries that implement this pattern such as ProxyManager, Proxy Manager LTS or even symfony/var-exporter. I do personally recommend using the latter when possible.

One of the biggest drawbacks of Ghost objects is that you need to create a class that extends the proxified class. It can block you if you want to proxify a class that is final but will work in most cases and none of the consumers or the proxified class has to know there is a ghost object there. More recently, we saw a Lazy Object RFC done by Nicolas Grekas & Arnaud Le Blanc, merged from the PHP team! Adding this feature to the core means we no longer need to create a proxy class, which is currently almost always required for lazy-loading.

Now that we’ve seen what lazy-loading is and what libraries can leverage it in PHP, let’s see how it is used in well known PHP libraries.

Symfony DependencyInjection

In Symfony, you can define a service as needing to be lazy-loaded in multiple ways. You can either define a service as being lazy-loaded or you can define one of the dependencies of a service as being lazy-loaded.

For instance, imagine you have a NewsletterManager and you inject a mailer service into it. Only a few methods on your NewsletterManager actually use the mailer, but even when you don’t need it, mailer service is always instantiated in order to construct your NewsletterManager.

Configuring lazy services is one answer to this. With a lazy service, a “proxy” of the mailer service is actually injected. It looks and acts like the mailer, except that the mailer isn’t actually instantiated until you interact with the proxy in some way.

To put it with examples, considering you have the following service:

readonly class NewsletterManager
{
  public function __construct(
	private MailerInterface $mailer,
  ) {
  }
}

When we use this service, we could have methods that don’t use the $mailer property. That’s why we don’t want to load it directly and we use lazy-loading. When you use the external mailer service, the mailer will be initialized and returned.

Based on the 4 types of lazy-loading we described, Symfony doesn’t use a single type but adapts based on what it requires. You can find more about lazy-loading service in Symfony in the related documentation page.

Doctrine

When you use Doctrine, you’ll sometimes have a lazy-loaded object so that it can trigger a database query only when the object is accessed. By making a direct request to an object, Doctrine will return the hydrated object, but sometimes our objects have relationships with other objects, so these relationships will be lazy-loaded. By default, the relationships are lazy-loaded (except for OneToOne relations), a proxy object will be returned instead of the real object, which will be loaded only if this object is accessed, which will also trigger a request to the database. You can avoid this behavior by using the fetch parameter with the value EAGER, you’ll get a real object directly.

In practice, you will have the following code for your entity:

#[ORM\Entity]
#[ORM\Table(name: 'customer')]
class User
{
  // some columns …

  #[ManyToOne(targetEntity: Address::class, nullable: true)]
  private ?Address $address = null;
}

And whenever you request an User, the Address object will be proxified. Doctrine will generate the following proxy:

class Address extends \App\Entity\Address implements \Doctrine\ORM\Proxy\InternalProxy
{
  use \Symfony\Component\VarExporter\LazyGhostTrait {
    initializeLazyObject as __load;
    setLazyObjectAsInitialized as public __setInitialized;
    isLazyObjectInitialized as private;
    createLazyGhost as private;
    resetLazyObject as private;
  }

  private const LAZY_OBJECT_PROPERTY_SCOPES = [
    "\0".parent::class."\0".'id' => [parent::class, 'id', null],
    "\0".parent::class."\0".'name' => [parent::class, 'name', null],
    // ... other fields
  ];

  // ... other methods
}

When you’re making a database query with Doctrine, the relations of the object you’re fetching will (depending on configuration) be proxified. Since those proxies extend your entity class, you will be able to use them the exact same way you usually use your entity.

Something different from Symfony’s DependencyInjection here is that each Doctrine proxy will contain an identifier (usually a numeric id) that will allow Doctrine to link a proxy instance to a row for the given entity in the database. We call that a LazyGhost.

And in your projects?

Now that we’ve seen the two most common uses of lazy-loading, how could you use this in your applications?

One of the best use cases I stumbled over upon my 13 years of development is curl requests. Not the simple curl request that you do to an external service, I mean thousands of curl requests that you probably will require at the same time… or maybe not.

The base issue

curl is one of those projects we can’t ignore in my developer’s life. There aren’t many of them but curl is clearly in that list. And after using curl all this time, we found some strange issues, 5 years ago, when trying to make some HTTP calls to an API.

First of all, why do we have to make thousands of requests to an API? we are working for an e-commerce company that has multiple services, and specifically one that is a PIM. That API is a product catalog. When we show a product page, we reach that API for the specific product we’re showing in order to gather data about this product. Also, when we show a collection page, we have multiple products so we have to reach that API for each product (and other stuff like product categories).

And the final encounter, exports. That company is often doing exports of all products that are currently in sale and thus making thousands of requests to that API.

In order to make all of this work, we could just wait for each HTTP call to be done on the pages or exports. But this could mean waiting for hundreds of calls to finish. At the moment our product detail call is between 200 to 300 ms, so for an export of 2000 products it would require 10min to wait just for API calls to be done, not counting deserialization of data because I’m using DTOs. For a collection page, we can have up to 200/300 products in the same page for the biggest ones which would take around 1 min for API calls only.

Linking the PIM

In order to solve this issue, we have to create a link with that PIM API so we can lazy-load its data. As we said before, Doctrine is often using proxies so why not using an entity to make that link? The idea here is that when we load an entity, one of the properties will contain a proxy of how the API response should be, and once you access it we will trigger the API call to return the API model.

We will need something to identify what is the entity that contains the proxy object:

#[ORM\Entity]
#[ORM\Table(name: 'product')]
class Product
{
  #[ORM\Column]
  public string $pimUuid;

  public string $pimObject;

  public function setPimUuid(string $pimUuid): void
  {
    $this->pimUuid = $pimUuid;
  }

  public function getPimUuid(): string
  {
    return $this->pimUuid;
  }

  public function setPimObject(object $pimObject): void
  {
    $this->pimObject = $pimObject;
  }

  public function getPimObject(): object;
  {
    return $this->pimObject;
  }
}

In addition to that entity, we need to listen to the loading of the Product entity, which can be done with a Doctrine listener. That listener will handle the proxy generation and insert the proxy into the pimObject property so we can trigger the curl call when it is required:

#[AsEntityListener(event: Events::postLoad)]
class PimListener
{
  public function postLoad(PostLoadEventArgs $args): void
  {
    /** @var object|PimInterface $entity */
    $entity = $args->getObject();

    if (!$entity instanceof Product) {
      return;
    }

    /** @var string $uuid */
    $uuid = $entity->getPimUuid();
    $entity->setPimObject($this->fetchPim($uuid));
  }

  private function fetchPim(string $uuid): object
  {
    $initializer = function (
      GhostObjectInterface $ghostObject,
      string $method,
      array $parameters,
      &$initializer,
      array $properties
    ) use ($uuid) {
      $initializer = null; // disable initialization
      // Checking if we got a result from PIM API
      if (!$ghostObject instanceof ProductDTO) {
        return false;
      }

      // do the actual curl call
      $pimProduct = $this->pimClient->getVariantItem($uuid);

      /**
        * For all object properties, we take property name then we guess the mutator
        * method and we use it for each property in order to hydrate the object
        */
      foreach (\array_keys($properties) as $property) {
        $parts = explode("\x00", $property);
        /** @var string $variable */
        $variable = \array_pop($parts);
        $mutator = sprintf('get%s', \ucfirst($variable));
        $properties[$property] = \call_user_func([$pimProduct, $mutator]);
      }

      return true;
    };

    return $this->factory->createProxy(ProductDTO::class, $initializer);
  }
}

With this implementation, whenever we get a Product entity from the database, we inject a GhostProxy into that entity. If we access a property of this object, we trigger the curl call. From this point, we could easily have PIM data within other parts of our application with ease, thanks to that hidden curl call, but that was only the beginning of issues.

For a simple product page, this would make the job easy but what about a showcase of multiple products or even exporting the whole product list? We would have to wait for the curl call to be made one by one … As explained before, we don’t want that.

Overcoming curl limits

With this implementation we could see some strange issues: from time to time, some curl requests towards the PIM API were dropping for like, no reason!? We did many investigations but could never reproduce the exact issue. After some time, we could tell that the issues would always happens when we had more than 400/500 curl calls to do in a row and stumbled upon this issue within Symfony.

When you’re using HttpClientin Symfony, you will, by default, use the CurlHttpClient which uses curl_multi under the hood to launch HTTP calls. Thanks to curl_multi, we have something close to asynchronous HTTP calls because we can trigger a HTTP call and use it later, but in the meantime curl_multi could already have received the result?

Since we knew what the issue was (number of concurrent requests when using curl_multi), we did the simplest change to fix this issue: batching. The idea was that instead of getting the Products one by one, we would use the product list endpoint onto the PIM API. That way we could get Product 25 per 25. From 500 curl calls, we dropped to 20 calls.

But we still had to wait for 20 calls to be made before we could start building our page. One product list call takes around ~120ms, but 20 times that would be 2.4s. And that’s only in the optimistic case where we only need products.

That’s why we combined the strengths of lazy-loading with the almost async Symfony CurlHttpClient to make the “preload” feature. Think about HTTP preload: we will start fetching data before it’s even used and when we access that data, it will probably already be there, or it will have started to call for it. That way we have the minimum possible time to wait for PIM data!

Let’s see it with some code:

final class Result
{
  private bool $initialized;

  public function __construct(
    private ResponseInterface $response,
    private string $modelClass, // DTO FQCN
    private SerializerInterface $serializer,
  ) {
    $this->initialized = false;
  }

  public function isInitialized(): bool
  {
    return $this->initialized;
  }

  public function getStatusCode(): int
  {
    $this->initialized = true;
    return $this->response->getStatusCode();
  }

  public function toObject(): ?object
  {
    return $this->serializer->deserialize($this->getContents(), $this->modelClass, 'json');
  }

  public function getContents(): string
  {
    $this->initialized = true;

    return $this->response->getContent();
  }
}

In the PimListener:

public function preload(array $entities): void
{
  foreach ($entities as $entity) {
    // some configuration pass based on the entity ...
    [$modelClass, $endpointClass] = $entity->getPimModelConfiguration();

    if (\array_key_exists($entity->getPimUuid(), $this->arrayResults[$modelClass])) {
      continue; // Do not fetch data we already have in current transaction
    }

    $endpoint = new $endpointClass($entity->getPimUuid());
    $response = $this->makeRequest($endpoint);
    $this->arrayResults[$modelClass][$entity->getPimUuid()] = new Result($response, $modelClass, $this->serializer);
  }
}

With this Result class and the preload method, we can load data before we need it. So now in my page controller, the first line is a query that gets all the products we will use during the rendering part. And we send that product array into the preload method. That way we start the curl queries and later on when we try to, for example, get the image of a product, it will be instantaneous!

Full PimListener code is available on this gist: https://gist.github.com/Korbeil/7451afbff73da572f0500375d6f74805

Conclusion

Now that you know what lazy-loading is and have an idea on how you can use it, we can’t wait to see all the new things the PHP community will find to do with this awesome tool. We wanted to make this post because we saw many comments about the recent RFC being too “niche” and “not something we need”. Now we can all see how lazy-loading could help us and make our projects more performant!

And with that new RFC?

Now that Lazy Object RFC was accepted, this code will not be the same anymore. Here is a quick peek on how it should looks based on the simple PimListener we made before:

#[AsEntityListener(event: Events::postLoad)]
class PimListener
{
  public function postLoad(PostLoadEventArgs $args): void
  {
    /** @var object|PimInterface $entity */
    $entity = $args->getObject();

    if (!$entity instanceof Product) {
      return;
    }

    /** @var string $uuid */
    $uuid = $entity->getPimUuid();
    $entity->setPimObject($this->fetchPim($uuid));
  }

  private function fetchPim(string $uuid): object
  {
    $reflector = new ReflectionClass(ProductDTO::class);
    $initializer = static function (ProductDTO $product) use ($reflector): void {
      $pimProduct = $this->pimClient->getVariantItem($product->getUuid());
      foreach ($reflector->getProperties() as $property) {
        $mutator = sprintf('get%s', \ucfirst($property->getName()));
        $reflector->getProperty($property)->setValue($post, \call_user_func([$pimProduct, $mutator]));
      }
    };

    $product = $reflector->newLazyGhost($initializer);
    $reflector->getProperty('uuid')->setRawValueWithoutLazyInitialization($product, $uuid);

    return $product;
  }
}

See how simple the implementation is with the RFC! And on top of that, you won’t need any third-party library to do that, it will be embedded into the PHP core! 🎉

Aujourd’hui, utiliser une crontab pour nos tâches récurrentes est assez courant mais pas très pratique car complètement déconnecté de notre application. Le composant Scheduler se présente comme une excellente alternative. Il a été introduit en 6.3 par Fabien Potencier lors de sa keynote d’ouverture du SymfonyLive Paris 2023. Le composant est maintenant réputé comme stable depuis la sortie de Symfony 6.4. Regardons comment l’utiliser !

Installation

Installons le composant :

composer require symfony/messenger symfony/scheduler

Comme toutes les fonctionnalités du composant se basent sur Messenger, il est nécessaire de l’installer aussi.

Une première tâche

Créons un premier message à planifier :

// src/Message/Foo.php
readonly final class Foo {}

// src/Handler/FooHandler.php
#[AsMessageHandler]
readonly final class FooHandler
{
    public function __invoke(Foo $foo): void
    {
        sleep(5);
    }
}

De la même manière qu’un Message dispatché dans Messenger, nous dispatchons ici un Message, que Scheduler traitera de façon similaire à Messenger, excepté que le déclenchement du traitement se fera sur une base temporelle

En plus du couple Message/Handler, nous avons besoin de définir un “Schedule” :

#[AsSchedule(name: 'default')]
class Scheduler implements ScheduleProviderInterface
{
    public function getSchedule(): Schedule
    {
        return (new Schedule())->add(
            RecurringMessage::every('2 days', new Foo())
        );
    }
}

Il va permettre d’indiquer à notre application que nous avons un Schedule “default” qui contient un message lancé tous les deux jours. Ici, la fréquence est simple, mais il est tout à fait possible de configurer cela plus finement :

RecurringMessage::every('1 second', $msg)
RecurringMessage::every('15 day', $msg)

# format relatif
RecurringMessage::every('next friday', $msg)
RecurringMessage::every('first sunday of next month', $msg)

# se lance à un horaire spécifique tous les jours
RecurringMessage::every('1 day', $msg, from: '14:42')
# vous pouvez donner un objet DateTime aussi
RecurringMessage::every('1 day', $msg,
    from: new \DateTimeImmutable('14:42', new \DateTimeZone('Europe/Paris'))
)

# définir la fin de la récurrence
RecurringMessage::every('1 day', $msg, until: '2023-09-21')

# vous pouvez aussi utiliser des expressions cron
RecurringMessage::cron('42 14 * * 2', $msg) // every Tuesday at 14:42
RecurringMessage::cron('#midnight', $msg)
RecurringMessage::cron('#weekly', $msg)

Ici, nous pouvons voir des formats relatifs; vous trouverez plus d’informations sur ce format en PHP sur la page de documentation.

Pour les syntaxes cron, il vous faudra installer une librairie tierce qui permet à Scheduler de les interpréter :

composer require dragonmantank/cron-expression

Une fois votre Schedule défini, comme pour un transport Messenger, il vous faudra un worker qui va écouter sur le Schedule de la façon suivante:

bin/console messenger:consume -v scheduler_default

Le préfix scheduler_ est le nom générique du transport pour tous les Schedule, auquel nous ajoutons le nom du Schedule créé.

Les collisions

Plus nous avons de tâches, plus nous avons de chances d’avoir des tâches qui vont arriver au même moment. Mais si une collision arrive, comment Scheduler va-t-il gérer ça ? Imaginons le cas suivant :

(new Schedule())->add(
    RecurringMessage::every('2 days', new Foo()),
    RecurringMessage::every('3 days', new Foo())
);

Tous les 6 jours, les deux messages vont entrer en collision :

Si nous avons qu’un seul worker, alors il prendra la première tâche configurée dans le Schedule puis, une fois la première tâche finie, il exécutera la seconde tâche. Autrement dit, l’heure d’exécution de la 2ème tâche est dépendante de la durée d’exécution de la 1ère.

Souvent nous voulons que nos tâches soient exécutées à un moment précis, pour régler ce soucis il existe deux solutions:

• La bonne pratique serait de préciser la date et heure d’exécution de notre tâche grâce au paramètre from, par exemple: RecurringMessage::every('1 day', $msg, from: '14:42') pour un des messages et fixer à 15:42 pour l’autre tâche (aussi possible avec une syntaxe cron) ;
• Avoir plusieurs workers qui tournent: si vous avez 2 workers, alors il pourra gérer 2 tâches en même temps !

Plusieurs workers ?

Mais aujourd’hui, si nous lançons 2 workers, notre tâche sera exécutée deux fois !

Scheduler fournit les outils pour éviter ça ! Mettons un peu à jour notre Schedule :

#[AsSchedule(name: 'default')]
class Scheduler implements ScheduleProviderInterface
{
    public function __construct(
        private readonly CacheInterface $cache,
        private readonly LockFactory $lockFactory,
    ) {
    }

    public function getSchedule(): Schedule
    {
        return (new Schedule())
            ->add(RecurringMessage::every('2 days', new Foo(), from: '04:05'))
            ->add(RecurringMessage::cron('15 4 */3 * *', new Foo()))
            ->stateful($this->cache)
            ->lock($this->lockFactory->createLock('scheduler-default'))
        ;
    }
}

Nous récupèrons un service pour gérer son cache et pour créer des locks (penser à installer symfony/lock auparavant). Puis nous indiquons que notre schedule peut maintenant bénéficier d’un état et possède un lock grâce à ces nouveaux éléments.

Et voilà 🎉, maintenant nous pouvons avoir autant de workers que nous voulons, ils ne lanceront pas plusieurs fois le même message :)

Du tooling !

Debug de nos Schedules

Une commande console a été ajoutée depuis cette PR, elle permet de lister toutes les tâches des Schedules que vous avez créé !

$ bin/console debug:scheduler

Scheduler
=========

default
-------

 -------------- -------------------------------------------------- ---------------------------------
  Trigger    	Provider                                       	Next Run                    	
 -------------- -------------------------------------------------- ---------------------------------
  every 2 days   App\Messenger\Foo(O:17:"App\Messenger\Foo":0:{})   Sun, 03 Dec 2023 04:05:00 +0000
  15 4 */3 * *   App\Messenger\Foo(O:17:"App\Messenger\Foo":0:{})   Mon, 04 Dec 2023 04:15:00 +0000
 -------------- -------------------------------------------------- ---------------------------------

En plus de voir les tâches de vos Schedules, vous aurez aussi la prochaine date d’exécution.

Changer le transport de vos tâches

Parfois un message peut prendre du temps à être traité. Il est donc possible de dire dans son Schedule que notre message doit être traité par un transport donné. Par exemple :

(new Schedule())->add(
    RecurringMessage::cron('15 4 */3 * *', new RedispatchMessage(new Foo(), ‘async’)))
);

Ici, quand le message doit être distribué, le worker va le renvoyer vers le transport async qui s’occupera alors de le traiter. Très pratique pour les tâches lourdes car cela libérera le worker scheduler_default pour traiter les prochains messages.

Gérer les erreurs

Scheduler permet d’écouter plusieurs événements via le composant EventDispatcher. Il existe 3 événements écoutables: PreRunEvent, PostRunEvent et FailureEvent. Les deux premiers seront déclenchés, respectivement, avant et après chaque tâche exécutée. Le dernier, quant à lui, sera lancé en cas d’exception dans une tâche. Cela peut être très pratique pour monitorer de façon efficace vos erreurs :

#[AsEventListener(event: FailureEvent::class)]
final class ScheduleListener
{
    public function __invoke(FailureEvent $event): void
    {
        // triggers email to yourself when your schedules have issues
    }
}

Avec ce code, lorsqu’un événement FailureEvent arrive, vous pourrez vous envoyer un email ou rajouter des logs pour mieux comprendre le soucis.

Console as Scheduler

Une des fonctionnalités les plus intéressantes de Scheduler selon moi : les attributs AsCronTask et AsPeriodicTask ! Ceux-ci permettent de transformer une commande console en une tâche périodique de façon très simple ! AsPeriodicTask permet de définir une tâche via une récurrence simple: 2 days par exemple, et AsCronTask permet de faire la même chose via une expression cron.

#[AsCommand(name: 'app:foo')]
#[AsPeriodicTask('2 days', schedule: 'default')]
final class FooCommand extends Command
{
    public function execute(InputInterface $input, OutputInterface $output): int
    {
        // run you command

        return Command::SUCCESS;
    }
}

Et voilà, la commande sera exécutée dans le Schedule default tous les 2 jours !

Nous retrouvons souvent des doublons entre les commandes console et vos tâches récurrentes, c’est la fonctionnalité parfaite pour faire le lien entre les deux !

Conclusion

Le composant Scheduler s’impose comme un outil essentiel pour intégrer efficacement les tâches récurrentes dans Symfony. Sa simplicité d’utilisation, sa flexibilité, la gestion des expressions cron, ainsi que son intégration transparente avec les commandes console en font un choix incontournable.

Dans la vie d’un développeur, il arrive forcément un moment où l’on doit traiter un volume important de données via une ligne de commande. Et les premières fois, ça fait BOOM 💥, on utilise du memory_limit=-1, des optimisations… Dans cet article, je dresse une liste des différents points d’attention qui m’ont déjà été utiles, ainsi que des astuces qui peuvent grandement aider à l’utilisation et à la maintenance de votre traitement. Attention, cette liste n’est pas exhaustive et les différents points peuvent être applicables ou non selon votre cas.

Astuces génériques

En premier, des conseils génériques qui peuvent s’appliquer dans la majorité des cas :

• Avoir un repère d’avancement. Cela peut paraître trivial, mais avoir une barre d’avancement ou un pourcentage permet de voir rapidement et facilement la quantité d’éléments à traiter et l’état d’avancement. Par exemple, Symfony propose une classe ProgressBar dans son composant Console qui permet de “calculer” le temps de traitement passé ou restant - estimé en fonction de la vitesse à laquelle nos éléments ont été traités jusqu’à présent - et la consommation mémoire. Voici un exemple :

ProgressBar::setFormatDefinition('custom', '%current%/%max% [%bar%] %percent:3s%% %elapsed:6s%/%estimated:-6s% %memory:6s% %message%');
$bar = $io->createProgressBar($count);
$bar->setMessage('Starting');
$bar->setFormat('custom');
$bar->start();

foreach ($items as $item) {
	$bar->setMessage(sprintf('Idem ID: %s', $item->getId()));
	$bar->advance();
}

$bar->finish();

Utiliser cette technique pose aussi deux soucis. Il faut pouvoir compter les éléments en amont, ce qui n’est pas toujours possible. Et il faut faire attention au taux de refresh du repère affiché en console pour parfois le réduire s’il est trop gourmand (il existe un paramètre sur la classe ProgressBar qui permet de gérer ça).

• Rendre son traitement tolérant aux erreurs, toujours traiter les erreurs via un channel de log ou via un rapport. Bien sûr, ce n’est pas une raison pour ignorer ces erreurs, pensez à regarder ce rapport et à agir en conséquence.
• Ne pas regrouper les traitements. Une tâche qui traite beaucoup d’éléments va prendre soit du temps, soit de la charge CPU ou elle peut juste planter. Si vous avez plusieurs actions à faire, séparez les en plusieurs commandes qui pourront être lancées indépendamment. J’ai déjà pu voir une commande qui gérait des statuts de paiements et qui faisait aussi la détection de fraude. Vous pouvez totalement séparer les deux actions en deux commandes et ainsi réduire la charge de vos commandes.
• Rendre votre commande relançable sans impact sur son exécution. En effet, il peut arriver d’avoir de très long processus qui bugguent au milieu, ou même que la commande soit trop longue pour être exécutée d’un coup. Il faudra donc pouvoir la lancer plusieurs fois. Pour cela, il existe plusieurs méthodes. La première serait d’utiliser un flag quand un élément est déjà traité, ce qui permettra de l’exclure au prochain passage. Une seconde méthode serait d’avoir une borne dans votre commande, par exemple --continue-after-id ou encore --continue-after-date - ici l’idée est d’avoir une borne à partir de laquelle on reprend le traitement des éléments.
• Attention à l’utilisation des fonction de manipulation de tableaux. Par exemple, un array_merge au milieu d’une boucle. Il vaut mieux regarder les alternatives pour faire ça en dehors de cette boucle. Vous pouvez aussi préparer votre donnée de base pour éviter d’avoir à faire ce genre de manipulation. De façon plus générale, il vaut mieux éviter tout ce qui utilise de la mémoire dans une boucle, car plus la boucle est grande, plus l’impact est important pour votre serveur.
• Un rapport à la fin vous sera toujours utile. Par exemple, avoir le nombre d’éléments traités, la durée de ce traitement, la quantité de mémoire utilisée, le nombre de requêtes SQL engendrées etc. Il est également intéressant d’ajouter des indicateurs métiers : par exemple si votre commande vérifie des paiements pour trouver des fraudes potentielles, avoir le nombre de paiements détectés comme “fraude” ou “validé” peut être pertinent.
• Paralléliser sur plusieurs workers permet aussi de beaucoup accélérer le traitement des données. Attention cependant, cela rendra tout de suite votre tâche beaucoup plus complexe car il va falloir partager votre traitement de base en plusieurs tâches en parallèle de façon indépendante.

Doctrine

Doctrine est souvent utilisé dans les applications Symfony et c’est l’une des sources de données les plus populaires. Je ne pouvais donc pas passer à côté d’une section concernant Doctrine 😀.

• Nettoyer l’EntityManager de Doctrine. De nombreuses requêtes vont faire que beaucoup d’objets seront instanciés et des fuites de mémoire vont apparaître à coup sûr. C’est pour cela qu’il est recommandé de nettoyer l’EntityManager à chaque tour de boucle ou dès que vous le pouvez grâce à la méthode EntityManager::clear().
• Préférer utiliser toIterable() sur les retours de requêtes avec beaucoup de résultats. En effet, lorsqu’on appelle getResult(), Doctrine va préparer toute la collection d’un coup, et donc potentiellement avec beaucoup d’éléments. En utilisant toIterable(), on aura les éléments hydratés un par un grâce à un générateur.
• Borner les requêtes. Il peut arriver que nos processus aient des éléments traités en erreur pour diverses raisons. C’est pour cela qu’il est recommandé de borner ses requêtes de façon temporelle (ne récupérer que les éléments des 3 derniers jours par exemple). Ainsi, lorsqu’un élément est traité en erreur, il ne sera automatiquement plus traité au bout de 3 jours (puisqu’il ne sera plus sélectionné). Cela permet de gagner du temps CPU sur vos serveurs une fois la borne dépassée. Une autre solution est de mettre un compteur de tentatives sur vos éléments et d’ignorer les éléments à partir d’un certain nombre de tentatives. Et encore une fois, n’oubliez pas de suivre et traiter ces erreurs !
• Réduire les combinatoires. Généralement, on préfère tout traiter dans une commande. Par exemple, si on a des paniers clients à supprimer, on fera une commande journalière pour supprimer les paniers expirés. Mais parfois, il vaut mieux traiter la tâche en plusieurs parties pour éviter de trop faire d’un coup. N’hésitez pas à diviser la tâche en plusieurs lots pour réduire leur taille ou leur temps de traitement. Par exemple, une première commande pour les paniers de la matinée et une seconde pour les paniers de l’après-midi.
• Utiliser des références plutôt qu’un find(). Quand on doit récupérer une référence à une entité, sans pour autant lui appliquer des traitements directement, il vaut mieux privilégier l’utilisation de getReference(Entity::class, $id). Cela renverra un proxy de l’objet demandé sans faire de requête vers la base de données, comme le ferait un find(). Vous pourrez trouver plus d’informations sur la méthode getReference dans la documentation Doctrine.
• Bien choisir le mode d’hydratation lors de l’utilisation de vos requêtes SQL. Par défaut, Doctrine met l’hydratation de vos requêtes à object. Il va alors transformer le résultat de la requête en un objet et garder en mémoire tous les objets ainsi créés. Cette hydratation d’objet va forcément prendre du temps. Ici, je vous recommande de passer par de l’hydratation array voire scalar (selon les besoins) pour réduire au maximum le temps de process de vos données par Doctrine.

  object - 113Mib -  575ms
  simple - 106Mib -  457ms
   array - 066Mib -  333ms
  scalar - 066Mib -  291ms

• Régler le cache Doctrine et sur votre base de données. Lorsqu’on fait de nombreuses fois la même requête avec possiblement des doublons, il peut être très utile de mettre en place du cache côté Doctrine. Pour cela il existe trois niveaux de cache dans Doctrine: d’abord le cache sur le mapping entre vos entités et les tables en base de données. Puis le Query cache, qui permet de mettre en cache la construction de la requête SQL depuis le DQL. Et le Result cache qui va permettre de conserver les résultats de votre requête pour les réutiliser si la requête venait à être exécutée une seconde fois. Les caches sur les metadata (donc le mapping) et la query sont activés par défaut dans Symfony. Aussi, il existe parfois, selon le moteur utilisé, un cache côté base de données qui permet de garder les résultats des requêtes pour ensuite répondre plus vite. Pour MySQL il est désactivé par défaut depuis 5.6 et ⚠️ il a été retiré depuis MySQL 8.0.

Fichier

Il est parfois nécessaire de traiter de la donnée provenant d’un fichier, ou bien d’écrire cette donnée dans un fichier.

• Générer le contenu du fichier via un fichier temporaire. Quand on doit créer de gros fichiers, le fait de les générer puis de les écrire sur le disque peut utiliser beaucoup de mémoire. C’est pour ça qu’il est recommandé de passer par un générateur et d’écrire dans un fichier temporaire (via l’utilisation de tmpfile()) ligne par ligne (au plus petit élément possible) puis d’envoyer le fichier temporaire. Cela évite d’avoir beaucoup de RAM occupée par la variable qui va stocker ces données et permet aussi de gérer plus facilement les soucis de données. Vous pouvez aussi générer votre propre fichier et utiliser des file_put_contents() pour écrire dedans, mais pour ma part, je suis plus habitué à fwrite donc la fonction tmpfile() est plus adaptée.
• Génération de fichiers en asynchrone. Lorsqu’on génère des fichiers, la tâche nous semble toujours rapide au début. Puis au fur et à mesure de l’évolution de notre code, le volume de ces fichiers augmente, les rendant de plus en plus lents à générer. C’est pour cela que je recommande de générer vos fichiers via un worker asynchrone. De la même manière, si vous travaillez sur une requête HTTP pour une API, vous pouvez envoyer la génération du fichier en tâche de fond. Après, vous pouvez soit mettre en place une interface pour récupérer vos fichiers, soit passer par un envoi de lien dans un email ou autre moyen de notifier la disponibilité du fichier généré.

Monitoring

Et pour finir, on aime traiter de la donnée, mais il faut aussi la surveiller !

• Lorsque vous faites du traitement de lots de données, pensez à surveiller les informations système de vos machines ! RAM, CPU, espace disque… on ne sait jamais ce qui peut poser souci, donc autant avoir un œil sur tout ce qui pourrait bloquer ou ralentir votre traitement. On peut imaginer de suivre la RAM utilisée ou disponible en combinaison d’une barre de progression. Aussi, je ne peux que vous recommander quelques outils comme Netdata ou l’utilisation de sondes de monitoring comme Datadog, Prometheus et bien d’autres.
• Faites attention au garbage collector de PHP. En effet, par défaut, le garbage collector de PHP passera automatiquement quand il détecte que 10,000 objets sont instanciés pour nettoyer tous les objets qui ne sont plus utilisés. Lorsque vous avez un processus sur beaucoup de données, il peut être intéressant de désactiver ce comportement du garbage collector pour le faire vous-même à la main. Plus d’informations sur la documentation PHP.
• Et bien sûr ajoutez des métriques métiers ! Par exemple, si l’on doit passer des commandes d’un statut “en attente” à “validé”, il peut être judicieux de mesurer le nombre de commandes traitées, le nombre de commandes validées ou encore le nombre d’erreurs. La moindre information vous aidera à comprendre votre tâche et suivre le traitement de ces données.

Vous pourrez aussi trouver des astuces pour monitorer votre code PHP simplement dans un de nos précédents articles de blog.

Pour finir

J’espère que ce billet vous aura permis d’apprendre des choses, n’hésitez pas à y revenir lorsque vous aurez à traiter des gros lots de données. Un peu comme une checklist pour voir ce que nous vous recommandons de faire dans ce cas là. Mais n’oubliez pas qu’il existe des outils de profiling qui vous feront remonter les métriques CPU, RAM, requêtes SQL… et qui vous permettront d’ajuster vos process avec plus de précision ! Je pense faire évoluer cette liste au fur et à mesure et pourquoi pas ajouter vos recommandations si vous en avez. 😀

Elasticsearch, on en parle partout mais on ne sait jamais par où commencer. Dans ce talk, je vous présente, avec les outils de 2023, comment mettre en place ce moteur de recherche dans un applicatif web, les optimisations à ne pas oublier et pleins d’autres conseils pour améliorer votre prise en main et reprendre confiance en Elasticsearch!

Links

https://twitter.com/ElasticFR/status/1633447473065721858 https://www.elasticon.com/event/e4d4b4ed-77a7-48d2-b711-74fea8341273/summary

EDIT: There were two typos in this article. In the formula we were wrong about the position of one of the arguments which made it wrong, we invite you to check again the formula so you can fix it too. And in the Elasticsearch painless script, a subtlety of the Java language will make a division of a double variable by a long variable outputting a long rounded (badly indeed) so you have to be sure all your variables are doubles. If you never read the article, it is now correct and you don’t have to worry about it!

Our modern life is dominated by ratings, whether we go shopping, to the restaurant and even when looking for a spa. But how do we make sure these ratings are accurate? How could you, with an Elasticsearch cluster, sort by these ratings?

In this post we will work with a list of Book. When using the average rating sorting, we will get strange results: a Book with only one vote and a 10 average rating on top of the listing followed by another one with 100 votes and an average rating of 9,2 - this doesn’t make any sense.

This is why you would want to use some complex formula to take everything into account. In this post we’ll present to you what the Bayesian average is and how you can use it with a database and Elasticsearch to improve your sorting.

Bayesian average, what?

A Bayesian average is a method of estimating the mean of a population using outside information, especially a pre-existing belief, which is factored into the calculation. This is a central feature of Bayesian interpretation. This is useful when the available data set is small.

From https://en.wikipedia.org/wiki/Bayesian_average.

I’m feeling the same as you are now: that quote didn’t help me understand and I was even more intrigued when reading this; what helped me was reading a practical usage of this method.

In our case, we have a Book resource that can be rated from 1 to 10. So all the users of our website can rate that Book and when the users are searching in the catalog, we want the default sorting to be based on this rating.

That’s why we want to weigh this average by the number of voters of all the Book. Here is a more comprehensive formula:

• “b” annotation refer to book related values;
• “ab” annotation refer to “all book” related values;
• “v” indicate the count of votes, so “Bv” will be the count of votes for a specific book, and “ABv” will be the count of votes for all the books;
• “c” indicate the count of related object;
• “a” will correspond to the average of the related object.

We did a sheet to see how that formula will behave based on several factors. So you can understand how the formula will distribute your elements based on their ratings.

Implementation

Now let’s apply this to our application! Here, we will use a Symfony application which allows us to bypass a lot of bootstrap and go directly to the interesting part. We have a database that contains users, books and ratings. Also, We have a book index in an Elasticsearch cluster that reflects our database books but normalized, with a extra field as following in our mapping:

mappings:
  dynamic: false
  properties:
    # other properties ...
    bayesianAverage:
      type: float

bayesianAverage will be used to sort the book index later on. We will need to fill that value. During index creation, we transform the Book entity into an Elasticsearch document, and we compute the Bayesian average.

class BookTransformer implements EntityTransformer
{
    private function createModel(Book $book, array $normalized): BookModel
    {
        $model = new BookModel();
        // some assignations to fill my model

        $distribution = $this->ratingsDistribution->get($book->getId());
        
        $ratings = new RatingModel();
        $ratings->set1($distribution[1]); // Count of "1" ratings for this book
        $ratings->set2($distribution[2]); // Count of "2" ratings for this book...
        $ratings->set3($distribution[3]);
        $ratings->set4($distribution[4]);
        $ratings->set5($distribution[5]);
        $ratings->set6($distribution[6]);
        $ratings->set7($distribution[7]);
        $ratings->set8($distribution[8]);
        $ratings->set9($distribution[9]);
        $ratings->set10($distribution[10]);
        $ratings->setCount(array_sum($distribution));
        $model->setRatings($ratings);

        $model->setBayesianAverage($this->bayesianAverage->compute($ratings));

        return $model;
    }
}

Here we have a RatingsDistribution service¹ we use to compile all votes for a given Book within an array of integers with all possible ratings! That way we can assign our Book model with the number of voters for each rating and the total count of voters. These values will be used later on to calculate the Bayesian average from inside Elasticsearch.

And we are also seeing a BayesianAverage service we used to do calculations. Here is what it looks like:

class BayesianAverage
{
    public function allVotesCount(): int
    {
        $result = $this->connection->fetchAssociative('SELECT COUNT(id) as count FROM rating;');

        return (int) $result['count'];
    }

    public function allAverageRating(): float
    {
        $result = $this->connection->fetchAssociative('SELECT AVG(r.rating) as average FROM rating r;');

        return (float) $result['average'];
    }

    public function allCount(): int
    {
        $result = $this->connection->fetchAssociative('SELECT COUNT(b.id) as count FROM book b;');

        return (int) $result['count'];
    }

    public function compute(RatingModel $bookRatings): float
    {
        $bookCount = 0 === $bookRatings->getCount() ? 1 : $bookRatings->getCount();
        $inter = $this->allCount() / ($bookCount + ($this->allVotesCount() / $bookCount));
        $avg = (($bookRatings->get1Count() * 1) + ($bookRatings->get2Count() * 2) + ($bookRatings->get3Count() * 3) + ($bookRatings->get4Count() * 4) + ($bookRatings->get5Count() * 5) + ($bookRatings->get6Count() * 6) + ($bookRatings->get7Count() * 7) + ($bookRatings->get8Count() * 8) + ($bookRatings->get9Count() * 9) + ($bookRatings->get10Count() * 10)) / $bookCount;

        return $inter * $avg + (1 - $inter) * $this->allAverageRating();
    }
}

For our implementation we will cache global variables with a 1 hour time to live:

• all Bookvotes count in a bayesian_all_votes key;
• all Book average rating in a bayesian_all_average_rating key;
• Book count in a bayesian_all_count key.

Then we have a calculate method which makes all required calculations to get our Bayesian average for a given Book ratings distribution. Now, we are able to fill our index on creation with a correct Bayesian average on all our Book models!

Handling new votes

But it works only on indexation, what happens if a user gives a new vote? All values we have calculated will be wrong and have to be refreshed!

First thing we will solve is updating the related model in Elasticsearch when a user is submitting a new vote on a Book. When we have a new vote, we will update the Elasticsearch model with a stored painless script² called bayesian-update in our Elasticsearch cluster. It will update the document values and update the bayesianAverage field, here is what the script will look like:

// only for updates
if (params.addedRating > 0) {
    ctx._source.ratings[params.addedRating.toString()]++;
    ctx._source.ratings['count']++;
}
if (params.removedRating > 0) {
    ctx._source.ratings[params.removedRating.toString()]--;
    ctx._source.ratings['count']--;
}

// classic Bayesian average calculations
long s1 = ctx._source.ratings['1'];
long s2 = ctx._source.ratings['2'];
long s3 = ctx._source.ratings['3'];
long s4 = ctx._source.ratings['4'];
long s5 = ctx._source.ratings['5'];
long s6 = ctx._source.ratings['6'];
long s7 = ctx._source.ratings['7'];
long s8 = ctx._source.ratings['8'];
long s9 = ctx._source.ratings['9'];
long s10 = ctx._source.ratings['10'];
double count = ctx._source.ratings['count'];

double inter = params.allCount / (count + (params.allVotesCount / count));
double avg = ((s1 * 1) + (s2 * 2) + (s3 * 3) + (s4 * 4) + (s5 * 5) + (s6 * 6) + (s7 * 7) + (s8 * 8) + (s9 * 9) + (s10 * 10)) / count;

ctx._source['bayesianAverage'] = inter * avg + (1 - inter) * params.allAverageRating;

This script use the following parameters:

• allCount corresponds to the method with the same name in our BayesianAverage service, it will contains the number of Book we have in our database;
• allVotesCount also corresponds to the method with the same name in our BayesianAverage service and it will contain the number of votes for all the Book;
• allAverageRating is also mirrored to the BayesianAverage service and contains the global average on all Book votes;
• then addedRating corresponds to the rating that was added on that Book;
• lastly, removedRating is here because in my application, a user can update his rating to another value so this field will contain the value that was removed if a user is updating his vote.

Now we can run our script each time there is a new vote by using this request onto the Elasticsearch cluster:

POST book/doc/67433/_update
{
  "script" : {
    "id": "bayesian-update",
    "params": {
      "addedRating": 7,
      "removedRating": 0,
      "allCount": 100,
      "allVotesCount": 30160,
      "allAverageRating": 6.51
    }
  }
}

That request will trigger an execution of the bayesian-update script on our model and update it automatically, without having to send the complete Book model again.

Keep the Bayesian average up-to-date

Now that new votes are managed, a big problem remains: Bayesian average is based on an average for a specific book, and the average for all books, so how can we be sure that our value is still relevant in time when more Book and votes are added?

In our case, we have a lot of Book and thanks to that, the difference in the Bayesian average result will be too small to be significant when new Book or new votes are added. That is why we chose to make a daily update on all our Book for the bayesianAverage field. This time frame should be based on your website traffic and if you need a really precise sorting or if some small variations are allowed. The more documents you have, the less frequently you will need to update since a new document won’t impact the global average that much.

For this update I created a new script called bayesian-refresh which is very similar to the first script but without the rating update part (so both addedRating and removedRating are not required parameters anymore).

To trigger this script, we use the bulk update API in Elasticsearch to run the script on all documents by selecting them by their ids as following:

POST book/_bulk
{"update": {"_id" : 67433}}
{"script" : {"id": "bayesian-refresh", "params" : {"allCount": 100, "allVotesCount": 30160, "allAverageRating": 6.51}}}
{"update": {"_id" : 67434}}
{"script" : {"id": "bayesian-refresh", "params" : {"allCount": 100, "allVotesCount": 30160, "allAverageRating": 6.51}}}
{"update": {"_id" : 67435}}
{"script" : {"id": "bayesian-refresh", "params" : {"allCount": 100, "allVotesCount": 30160, "allAverageRating": 6.51}}}
{"update": {"_id" : 67436}}
{"script" : {"id": "bayesian-refresh", "params" : {"allCount": 100, "allVotesCount": 30160, "allAverageRating": 6.51}}}
{"update": {"_id" : 67437}}
{"script" : {"id": "bayesian-refresh", "params" : {"allCount": 100, "allVotesCount": 30160, "allAverageRating": 6.51}}}

Sadly Elasticsearch doesn’t provide a way to trigger a script on all documents of an index so we’re forced to do it that way³.

Conclusion

Thanks to this formula and Elasticsearch we are now able to sort our Book listing per ratings based on the whole population of Book which makes this sort even more relevant! If you need this, you should consider “freshness” of the votes, in our case it doesn’t matter but in some projects, you will want to put less weight on an older vote. But thanks to this post you should be able to setup a basic sort based on your newly Bayesian average field 🎉.

GET book/_search
{
  "query": {
    "match_all": {}
  },
 "sort": [
    { "bayesianAverage": "desc" }
  ]
}

This post was greatly inspired by: https://www.evanmiller.org/bayesian-average-ratings.html If you want more mathematical details you should take a look ! 😉 Also our formula won’t match that one because we simplified some concepts and removed others, like time, since we don’t need these in our case.

Avant même d’effectuer une recherche dans Elasticsearch, vous devez l’alimenter avec vos données. Dans cet présentation, je passerai en revue tous les moyens que nous avons utilisés pour envoyer des millions de documents à nos index, des plus mauvais aux plus optimisés.

Mais même avec les optimisations, l’ingestion peut prendre du temps. Pendant ce temps, notre index en ligne pourrait avoir des opérations d’écriture que nous devons également répliquer sur notre nouvel index ! Je vous expliquerai donc aussi comment nous avons propagé ces changements aux deux index pour que tout aille bien une fois le nouvel index en ligne.

Video

Embed are blocked for this talk, but you can see the video on Elastic website: https://community-conference.elastic.co/session/305686

Sometimes, you need to put some custom rate limits on your APIs! In this article I’ll show you how you can combine the symfony/rate-limiter component and some usual controllers.

RateLimit configuration

The goal here is to have the following rate limit configuration works thanks to PHP8 attributes on any route you want:

framework:
  rate_limiter:
    account_create:
      policy: 'fixed_window'
      limit: 5
      interval: '60 minutes'
    account_modify: # account activate, change profile
      policy: 'fixed_window'
      limit: 30
      interval: '60 minutes'

This article isn’t about the component itself so I’ll recommend you to read the Symfony’s RateLimiter documentation if you want to understand how it works and how to create rules.

Attribute

First of all, we need an attribute that we will use to declare routes that need to be rate limited. We will require a configuration key to identify which rate limit configuration we should take:

#[Attribute(Attribute::TARGET_METHOD)]
class RateLimiting
{
  public function __construct(
    public string $configuration,
  ) {
  }
}

Controller

Now let’s use our attribute on some controller:

#[RateLimiting('account_create')]
#[Route('/create', methods: ['POST'])]
public function createAccount(): JsonResponse
{
  // your controller logic ...
}

And that’s all you need to do to declare a route as rate limited 👌

CompilerPass

But before it works we need to make Symfony understand these attributes. So we need a CompilerPass to store all routes that have our attribute to avoid reflection at runtime:

class RateLimitingPass implements CompilerPassInterface
{
  public function process(ContainerBuilder $container): void
  {
    if (!$container->hasDefinition(ApplyRateLimitingListener::class)) {
      throw new \LogicException(sprintf('Can not configure non-existent service %s', ApplyRateLimitingListener::class));
    }

    $taggedServices = $container->findTaggedServiceIds('controller.service_arguments');
    /** @var Definition[] $serviceDefinitions */
    $serviceDefinitions = array_map(fn (string $id) => $container->getDefinition($id), array_keys($taggedServices));

    $rateLimiterClassMap = [];

    foreach ($serviceDefinitions as $serviceDefinition) {
      $controllerClass = $serviceDefinition->getClass();
      $reflClass = $container->getReflectionClass($controllerClass);

      foreach ($reflClass->getMethods(\ReflectionMethod::IS_PUBLIC | ~\ReflectionMethod::IS_STATIC) as $reflMethod) {
        $attributes = $reflMethod->getAttributes(RateLimiting::class);
        if (\count($attributes) > 0) {
          [$attribute] = $attributes;

          $serviceKey = sprintf('limiter.%s', $attribute->newInstance()->configuration);
          if (!$container->hasDefinition($serviceKey)) {
            throw new \RuntimeException(sprintf(‘Service %s not found’, $serviceKey));
          }

          $classMapKey = sprintf('%s::%s', $serviceDefinition->getClass(), $reflMethod->getName());
          $rateLimiterClassMap[$classMapKey] = $container->getDefinition($serviceKey);
        }
      }
    }

    $container->getDefinition(ApplyRateLimitingListener::class)->setArgument('$rateLimiterClassMap', $rateLimiterClassMap);
  }
}

Here we get all controllers and we check on each method if they have our attribute and then we link the route to the corresponding rate limit service and add it in our cache.

Listener

Now that Symfony understands our attribute and cache it, we need an event listener to hook on the kernel.controller event and check if our rate limit is fine or not.

class ApplyRateLimitingListener implements EventSubscriberInterface
{
  public function __construct(
    private TokenStorageInterface $tokenStorage,
    /** @var RateLimiterFactory[] */
    private array $rateLimiterClassMap,
    private bool $isRateLimiterEnabled,
    private RequestStack $requestStack,
    private RoleHierarchyInterface $roleHierarchy,
  ) {
  }

  public function onKernelController(KernelEvent $event): void
  {
    if (!$this->isRateLimiterEnabled || !$event->isMainRequest()) {
      return;
    }

    $request = $event->getRequest();
    /** @var string $controllerClass */
    $controllerClass = $request->attributes->get('_controller');

    $rateLimiter = $this->rateLimiterClassMap[$controllerClass] ?? null;
    if (null === $rateLimiter) {
      return; // no rate limit service was assigned for this controller
    }

    $token = $this->tokenStorage->getToken();
    if ($token instanceof TokenInterface && in_array('ROLE_GLOBAL_MODERATOR', $this->roleHierarchy->getReachableRoleNames(($token->getRoleNames())))) {
      return; // we ignore rate limit for site moderator & upper roles
    }
    
    $this->ensureRateLimiting($request, $rateLimiter, $request->getClientIp());
  }

  private function ensureRateLimiting(Request $request, RateLimiterFactory $rateLimiter, string $clientIp): void
  {
    $limit = $rateLimiter->create(sprintf('rate_limit_ip_%s', $clientIp))->consume();
    $request->attributes->set('rate_limit', $limit);
    $limit->ensureAccepted();

    $user = $this->tokenStorage->getToken()?->getUser();
    if ($user instanceof User) {
      $limit = $rateLimiter->create(sprintf('rate_limit_user_%s', $user->getId()))->consume();
      $request->attributes->set('rate_limit', $limit);
      $limit->ensureAccepted();
    }
  }

  public static function getSubscribedEvents(): array
  {
    return [KernelEvents::CONTROLLER => ['onKernelController', 1024]];
  }
}

In this example, I chose to ignore rate limits for our global moderator roles. For all other users I check the rate limit on two levels: IP then User if they are logged. That way we can avoid any user spamming from different IPs. These are business rules I use but you can custom it the way you want.

Also you can see that we share the rate limit service before each check: if there is a rate limit issue then an exception will be thrown (thanks to the ensureAccepted method) and the second check won’t happen so we will have the correct rate limit service shared.

Headers

Finally, to use that shared rate limit service, we can generate some headers to indicate how the rate limit went and other metrics:

final class RateLimitingResponseHeadersListener
{
  public function onKernelResponse(ResponseEvent $event): void
  {
    if (($rateLimit = $event->getRequest()->attributes->get('rate_limit')) instanceof RateLimit) {
      $event->getResponse()->headers->add([
        'RateLimit-Remaining' => $rateLimit->getRemainingTokens(),
        'RateLimit-Reset' => time() - $rateLimit->getRetryAfter()->getTimestamp(),
        'RateLimit-Limit' => $rateLimit->getLimit(),
      ]);
    }
  }
}

I took the headers names from the RateLimit headers RFC, it’s still a draft but theses headers are already widely used.

And here we are - with only a few lines of code, you can add a rate limit to any route by adding your new RateLimiting attribute!

It is quite common for a developer to have to map data. In the long run, this kind of code is boring to write. Why not generate it automatically? This is the promise that AutoMapper tries to solve: generating the code needed to map one data to another (array, class, etc.)

Through this talk, we will first see the Symfony Serializer and how it works.

Then, we will discover how AutoMapper takes advantage of the Serializer ecosystem while revolutionizing the Normalizer concept by adding code generation, thus drastically boosting performance!

Video

Available here: https://live.symfony.com/account/replay/video/593

Also, slides are available there: https://speakerdeck.com/korbeil/you-need-an-automapper-but-you-dont-know-it-yet