JoliCode blog - les derniers articles

Notre outillage front-end en 2025

2025-02-04T10:42:00+01:00

Nous sommes désormais 3 intégrateurs et intégratrices chez JoliCode. Afin d’harmoniser nos façons de faire, nous avons décidé de créer un projet vide, une sorte de « front-end starter » qui nous permettrait de démarrer une intégration. Il se base sur Symfony, le framework pour lequel nous sommes experts et intègre l’ensemble des outils, librairies et configurations que nous souhaitons utiliser côté front-end.

Voici un tour d’horizon de notre front-end starter et des différents choix que nous avons fait pour optimiser la qualité de nos intégrations.

Gestionnaire de paquets : passage à pnpm

Face à l’engouement autour de pnpm (pour Performant npm), nous nous sommes intéressés à ce gestionnaire de dépendances dont la promesse est d’être beaucoup plus rapide et performant que ses concurrents. Il repose sur le principe de liens symboliques afin de partager les dépendances entre plusieurs projets à un seul endroit. Concrètement, si une même librairie est utilisée sur deux projets différents, celle-ci ne sera stockée qu’à un endroit et le dossier node_modules contiendra un lien symbolique vers cette ressource. On peut enfin se débarrasser de ce dossier toujours plus lourd que l’on se coltine sur chaque projet.

Avec sa version 4, Yarn a rattrapé son retard avec sa stratégie Plug’n’Play. Ayant expérimenté pnpm au préalable, nous avons toutefois décidé de rester sur cet outil. Il a, pour le moment, répondu à nos attentes en nous offrant un confort de développement supplémentaire grâce à sa vitesse.

Maintien des standards avec les linters

L’utilisation de linters nous permet d’assurer une cohérence dans le code de nos projets. Le fait de l’intégrer à notre starter garantit le partage des standards à l’ensemble de ceux-ci. Nous ne faisons pas dans l’originalité à ce niveau-là puisque nous utilisons eslint pour le code JavaScript et stylelint pour le css.

Pas de configuration vraiment particulière pour eslint, nous nous basons sur @eslint/js et utilisons la configuration recommended. Pour stylelint, en plus de la configuration standard, nous nous assurons de respecter un certain ordre pour nos règles CSS en surchargeant quelques règles comme selector-class-pattern pour nous permettre d’utiliser la notation BEM. Dans les deux cas, nous utilisons prettier pour formater plus facilement notre code selon les règles définies.

Les outils côté CSS

La fin de SASS

Comme nous en avions parlé dans un précédent article, nous avons décidé de ne plus utiliser le préprocesseur SASS et de nous baser uniquement sur PostCSS. Agrémenté de plugins, il nous permet de retrouver nos automatismes avec l’utilisation d’un préprocesseur (imbrication, mixins…), en supprimant toutefois un outil de notre stack. Nous avons évidemment ajouté le plugin autoprefixer afin de gérer automatiquement l’ajout de préfixes CSS.

Tailwind

Côté framework, nous n’avons pas échappé à la tendance Tailwind. Nous avons décidé de l’intégrer à nos projets, mais pas n’importe comment. Nous utilisons une approche "hybride" : nous n’avons pas supprimé l’utilisation de feuilles de style, nous créons toujours des composants et des classes sémantiques. Cependant, nous les agrémentons des classes utilitaires de tailwind pour nous simplifier la vie. Concrètement, nous créons une classe .btn pour nos boutons. Mais si nous souhaitons ajouter une marge à un bouton en particulier, nous pouvons le faire simplement avec les classes de tailwind. Jonathan a présenté une conférence à Codeurs en Seine pour expliquer notre approche et comment nous l’implémentons.

Nous utilisons actuellement la version 3 du framework mais la dernière version étant sortie cette semaine, nous prévoyons une mise à niveau très rapidement.

L’écosystème Symfony UX

Stimulus

Symfony UX est un ensemble de librairies permettant d’intégrer des outils JavaScript dans nos applications. L’une des librairies principales de Symfony UX est Stimulus, un framework JavaScript minimaliste. C’est une librairie que j’affectionne particulièrement à titre personnel et que j’ai commencé à utiliser il y a plusieurs années au sein de projets Ruby on rails. Elle permet d’organiser son code JavaScript en controlleurs et fonctionne directement sur du HTML (Twig) existant. Pour nos projets sans React, l’utilisation de Stimulus nous permet donc d’avoir un code propre et organisé malgré tout, mais aussi de gagner du temps.

Nous l’avons agrémenté de Stimulus Use qui permet d’utiliser de nouvelles fonctions de cycle de vie au sein d’un controlleur (comme appear, mouseEnter, ou resize).

Les composants Twig

Au sein de Symfony UX, les Twig Components nous permettent de séparer nos éléments en composants réutilisables. Un composant est constitué le plus souvent d’une classe PHP et d’un template Twig associé (il est également possible de créer des composants anonymes qui ne sont constitués que d’un template). Cela nous permet de créer un template pour chaque élément réutilisable (un bouton, une modale…). Nous avions l’habitude d’utiliser le tag embed sur certains projets pour reproduire ce principe de composants Twig mais cela produisait du code peu lisible.

Pour ajouter de l’interactivité à nos composants, nous avons également choisi d’inclure la librairie Live Components. Elle permet de mettre à jour un composant en Ajax lorsque l’utilisateur interagit avec, le tout sans écrire une ligne de JavaScript. C’est une librairie bien pratique dans le cas de composants interactifs, qu’on doit mettre à jour sans rechargement de page et qui nous fait gagner beaucoup de temps.

Certaines voix au sein de Jolicode s’élèvent pour l’utilisation d’HTMX. Nous avons privilégié pour l’instant l’utilisation des outils officiels recommandés par Symfony mais il n’est pas exclu que nous étudions une autre possibilité. Sur un projet récent les Live Components nous ont semblé en effet un peu difficiles à prendre en main et pas forcément adaptés pour répondre à toutes les situations.

Enfin, pour présenter nos composants nous avons décidé d’intégrer Storybook grâce au bundle de SensioLabs. Nous pouvons ainsi visualiser nos différents composants et leurs variantes facilement et ainsi constituer un design system. Auparavant, le design system était un simple template dans lequel nous ajoutions, à la main, les différents composants d’un site. Storybook nous offre une interface complète pour documenter nos composants front.

Gestion des assets

Pour faire fonctionner tout ce petit monde et gérer nos assets, nous utilisons Webpack intégré dans Webpack Encore. Nous avons expérimenté l’utilisation d’Asset Mapper mais malheureusement, au vu des outils que nous utilisons actuellement, nous ne sommes pas prêts à nous passer d’un bundler. Rien de révolutionnaire concernant sa configuration, nous y ajoutons nos linters, Stimulus, PostCSS et de quoi optimiser nos images.

Côté JavaScript enfin, nous ajoutons la librairie Babel pour s’assurer de la compatibilité de notre code.

Quelques librairies JavaScript utiles

Nous avons décidé de n’inclure que peu de librairies JavaScript par défaut dans notre projet starter. Le nombre de librairies qui se retrouvent sur la quasi-totalité de nos projets étant peu nombreux. Nous avons inclus a11y-dialog, une librairie légère créée par Kitty Giraudel qui permet de créer des modales accessibles. Comme elle ne contient pas de style par défaut, nous avons ajouté une feuille de style toute simple qui gère simplement l’affichage d’une modale avec overlay.

Enfin nous échappons rarement à la présence de sliders sur les sites que nous implémentons. Sur ce point, nous avons choisi d’intégrer la libraire Swiper, l’une des rares à répondre à l’ensemble de nos cas d’usage.

Nos outils en image

Et pour la suite ?

Ce projet n’est bien sûr pas figé et son utilisation au fil du temps pourrait nous amener à effectuer des ajustements. Nous pourrions challenger l’utilisation des live components et pnpm, ajuster notre configuration PostCSS au cours des avancées de CSS ou bien ajouter un linter Twig.

MCP: The Open Protocol That Turns LLM Chatbots into Intelligent Agents

2025-01-30T09:42:00+01:00

LLMs have started to become widely known. They are used to generate text, answer questions, translate texts, and more. These models are becoming increasingly powerful and are employed across diverse fields.

LLMs powers all the fancy IA you use like GPT, BERT, Claude, LLaMA, Deepseek, or Mistral.

We are reaching a point where LLMs have become smart enough. The next goal is enabling them to perform actions. For example, we want to be able to book a train or order a pizza directly from a chatbot.

The next step is to transform the LLM into a real assistant, an agent.

This is where MCP comes in. It is a protocol that allows a client to interact with a server capable of performing actions. The client sends a request to the server, which executes the action and returns the result.

Genesis of the Protocol

Some LLMs already support tools, but these are usually proprietary solutions. MCP aims to standardize how LLMs interact with tools.

On November 25, 2024, Anthropic announced the release of MCP. The protocol is open-source and free to use, designed to be simple and easy to implement.

On the official website, they describe MCP as:

MCP is an open protocol that standardizes how applications provide context to LLMs. Think of MCP like a USB-C port for AI applications. Just as USB-C provides a standardized way to connect your devices to various peripherals and accessories, MCP provides a standardized way to connect AI models to different data sources and tools.

How It Works

The Big Picture

At its core, MCP follows a client-server architecture where a host application connects to multiple servers:

MCP Hosts: Programs like Claude Desktop, IDEs, or AI tools that want to access data through MCP. Hosts can run multiple clients;
MCP Clients: Protocol clients that maintain 1:1 connections with servers;
MCP Servers: Lightweight programs exposing specific capabilities through the standardized Model Context Protocol — for example, a pizza delivery API or a train booking service.

For instance, when you use Claude Desktop (the host), you can configure it to interact with your application (the server). Claude Desktop may have many clients interacting with your application.

In this article, we'll focus on the server side, where the most interesting things happen because it's your application — the space for creativity! 🚀

Transports

How does the client communicate with the server? There are two methods:

STDIO

The client spawns the server as a child process and communicates through standard input/output (STDIN/STDOUT):

HTTP with Server-Sent Events

The client connects to the server via HTTP, and the server sends events back:

Messaging

The client-server connection is stateful and persistent. While this approach might not align with serverless architecture, it enables interesting use cases.

Once the client connects to the server, it can send requests. The server processes the request and sends back a response. The client may then send another request. Additionally, the server can send notifications, maintaining the persistent connection.

Messages follow the JSON-RPC 2.0 standard:

--> {"jsonrpc": "2.0", "method": "subtract", "params": [42, 23], "id": 1}
<-- {"jsonrpc": "2.0", "result": 19, "id": 1}

Learn more about types of messages ⬇

Types of Messages

Request: The client sends a request to the server.

{
    jsonrpc: "2.0";
    id: string | number;
    method: string;
    params?: {
        [key: string]: unknown;
    };
}

Response: The server sends a response to the client.

{
    jsonrpc: "2.0";
    id: string | number;
    result?: {
        [key: string]: unknown;
    };
    error?: {
        code: number;
        message: string;
        data?: unknown;
    }
}

Notification: The server pushes a notification to the client.

{
    jsonrpc: "2.0";
    method: string;
    params?: {
        [key: string]: unknown;
    };
}

Lifecycle

The connection lifecycle:

Initialization Phase

During this phase:

Protocol version compatibility is established;
Capabilities are exchanged and negotiated;
Implementation details are shared.

Learn more about request / response shape ⬇

Client initialize request example:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2024-11-05",
    "capabilities": {
      "roots": {
        "listChanged": true
      },
      "sampling": {}
    },
    "clientInfo": {
      "name": "ExampleClient",
      "version": "1.0.0"
    }
  }
}

Server initialize response example:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "protocolVersion": "2024-11-05",
    "capabilities": {
      "logging": {},
      "prompts": {
        "listChanged": true
      },
      "resources": {
        "subscribe": true,
        "listChanged": true
      },
      "tools": {
        "listChanged": true
      }
    },
    "serverInfo": {
      "name": "ExampleServer",
      "version": "1.0.0"
    }
  }
}

Operation Phase

During this phase, the client executes methods exposed by the server. The server may also send notifications.

Shutdown

The client can disconnect, closing the connection.

What Can a Server Do?

Servers provide the foundational building blocks for adding context to language models via MCP. These primitives enable rich interactions between clients, servers, and language models:

Prompts: Predefined templates or instructions that guide language model interactions. These are initiated by the user. Examples include slash commands and menu options;
Resources: Structured data or content that provides additional context to the model. Examples include file contents and git history;
Tools: Executable functions that allow models to perform actions or retrieve information.

Detailing all of these would make the article too lengthy. Hence, we’ll focus on Tools, the most intriguing and powerful aspect of the protocol.

How to Implement Tools in an MCP Server

At JoliCode, we primarily use PHP and Symfony, so we’ll demonstrate how to implement an MCP server in PHP using Symfony. For simplicity, we’ll utilize the stdio transport.

Our server will support two actions:

Listing all current Symfony commands;
Executing a Symfony command.

As of now, no official PHP library exists for MCP. We attempted to use logiscape/mcp-sdk-php but without success. Therefore, we’ll implement the protocol ourselves.

Note: This is a proof of concept (POC) and not production-ready code ⚠

We’ll use a Symfony command to start the server:

namespace App\Command;

use Symfony\Component\Console\Attribute\AsCommand;
use Symfony\Component\Console\Command\Command;
use Symfony\Component\Console\Input\ArrayInput;
use Symfony\Component\Console\Input\InputInterface;
use Symfony\Component\Console\Output\BufferedOutput;
use Symfony\Component\Console\Output\OutputInterface;

#[AsCommand(
    name: 'mcp',
    description: 'Starts an MCP server',
)]
class McpCommand extends Command
{
    protected function execute(InputInterface $input, OutputInterface $output): int
    {
    }
}

Reading Input from STDIN

The first step is to read the content from STDIN, buffer it, and decode it:

protected function execute(InputInterface $input, OutputInterface $output): int
{
    $buffer = '';

    while (true) {
        $line = fgets(STDIN);
        if (false === $line) {
            usleep(1000);
            continue;
        }
        $buffer .= $line;
        if (str_contains($buffer, "\n")) {
            $lines = explode("\n", $buffer);
            $buffer = array_pop($lines);
            foreach ($lines as $line) {
                $this->processLine($output, $line);
            }
        }
    }

    return Command::SUCCESS;
}

Processing the Input

We decode the JSON payload, invoke the appropriate method, and return the response:

private function processLine(OutputInterface $output, string $line): void
{
    try {
        $payload = json_decode($line, true, JSON_THROW_ON_ERROR);

        $method = $payload['method'] ?? null;

        $response = match ($method) {
            'initialize' => $this->sendInitialize(),
            'tools/list' => $this->sendToolsList(),
            'tools/call' => $this->callTool($payload['params']),
            'notifications/initialized' => null,
            default => $this->sendProtocolError(sprintf('Method "%s" not found', $method)),
        };
    } catch (\Throwable $e) {
        $response = $this->sendApplicationError($e);
    }

    if (!$response) {
        return;
    }

    $response['id'] = $payload['id'] ?? 0;
    $response['jsonrpc'] = '2.0';

    $output->writeln(json_encode($response));
}

Listing Tools

Here is the tools/list method, which provides a list of available tools:

private function sendToolsList(): array
{
    return [
        'result' => [
            'tools' => [
                [
                    'name' => 'list_commands',
                    'description' => 'List all Symfony commands.',
                    'inputSchema' => [
                        'type' => 'object',
                        '$schema' => 'http://json-schema.org/draft-07/schema#',
                    ],
                ],
                [
                    'name' => 'call_command',
                    'description' => 'Call a Symfony command.',
                    'inputSchema' => [
                        'type' => 'object',
                        'properties' => [
                            'command_name' => ['type' => 'string'],
                        ],
                        'required' => ['command_name'],
                        'additionalProperties' => false,
                        '$schema' => 'http://json-schema.org/draft-07/schema#',
                    ],
                ],
            ],
        ],
    ];
}

As you can see, we have two tools: list_commands and call_command. The inputSchema is a JSON schema that describes the tool's input. It'll document how the LLM can use it.

The more descriptive you are, the better it is for the LLM! It's like the SEO 😎! (Here, descriptions are really too shorts 🙈)

You can add as many tools as you want. By the way, instead of these two tools, we could have added one tool per Symfony command (just noticed that while writing this article 🤯). I think it would have been better, because we could have typed all command arguments / options. Anyway, let's continue.

Typically, the request would be:

{
  "jsonrpc": "2.0",
  "id": 4,
  "method": "tools/list",
  "params": {}
}

And the response would be:

{
  "result": {
    "tools": [
      {
        "name": "list_commands",
        "description": "List all symfony commands.",
        "inputSchema": {
          "type": "object",
          "$schema": "http://json-schema.org/draft-07/schema#"
        }
      },
      {
        "name": "call_command",
        "description": "Call a symfony command.",
        "inputSchema": {
          "type": "object",
          "properties": {
            "command_name": {
              "type": "string"
            }
          },
          "required": [
            "command_name"
          ],
          "additionalProperties": false,
          "$schema": "http://json-schema.org/draft-07/schema#"
        }
      }
    ]
  },
  "id": 4,
  "jsonrpc": "2.0"
}

Handling Tool Requests

Next, we define how to handle a tool call:

private function callTool(array $params): array
{
    $name = $params['name'];
    $arguments = $params['arguments'] ?? [];

    return match ($name) {
        'list_commands' =>  $this->callCommand('list', ['--format' => 'md']),
        'call_command' => $this->callCommand($arguments['command_name']),
        default => $this->sendProtocolError(sprintf('Tool "%s" not found', $name)),
    };
}

private function callCommand(string $commandName, array $parameters = []): array
{
    $command = $this->getApplication()->find($commandName);

    $input = new ArrayInput(['command' => $command, ...$parameters]);
    $output = new BufferedOutput();

    $command->run($input, $output);

    return [
        'result' => [
            'content' => [
                [
                    'type' => 'text',
                    'text' => $output->fetch(),
                ],
            ],
        ],
    ];
}

Here we go, we have implemented the two tools. The list_commands tool will list all Symfony commands, and the call_command tool will call a Symfony command.

If the LLM decided to clear the cache, the request would be:

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "_meta": {
      "progressToken": 0
    },
    "name": "call_command",
    "arguments": {
      "command_name": "cache:clear"
    }
  }
}

And the response would be:

{
  "result": {
    "content": [
      {
        "type": "text",
        "text": "\n // Clearing the cache for the dev environment with debug true                  \n\n [OK] Cache for the \"dev\" environment (debug=true) was successfully cleared.    \n\n"
      }
    ]
  },
  "id": 2,
  "jsonrpc": "2.0"
}

Demo time!

To use our new server, we need to configure it in a host. We'll use Claude Desktop.

In Claude Desktop's configuration, we can add as many servers as we want:

// ~/.config/Claude/claude_desktop_config.json
{
  "mcpServers": {
    "symfony_app": {
      // We don’t run PHP directly to have better debugging. We’ll talk about it later
      "command": "/home/gregoire/dev/labs/symfony/mcp/bin/mcp.sh"
    },
    // Another server, for example a filesystem server to explore a folder
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/home/gregoire/Downloads/video"
      ]
    }
  }
}

Then you can chat with it like usual:

Debugging

Debugging can be tricky without the right tooling! Here are some tips:

You can use the stderr to log errors but this is not useful. You can also use the logging capability to send logs to the client. But when nothing works, well, logging does not work either.

I created this small bash wrapper to log everything (STDIN, STDOUT, STERR) to some files to see what's going on:

#!/bin/bash
#mcp.sh


set -e
set -o pipefail

BASE=$(dirname $0)/..

date >> "$BASE/run.log"

stdin_log="$BASE/stdin.log"
stdout_log="$BASE/stdout.log"
stderr_log="$BASE/stderr.log"

tee -a "$stdin_log" | \
  $BASE/bin/console mcp > >(tee -a "$stdout_log") 2> >(tee -a "$stderr_log" >&2)

Additionally, the MCP Inspector is invaluable:

npx @modelcontextprotocol/inspector

Security Considerations

Each time Claude Desktop connects to a server to execute a tool, it prompts the user to accept the connection. While this is a great security measure, exposing tools like database management requires caution to avoid unintended consequences.

Conclusion

I do think building an LLM agent is the next big step in generative IA. The agent must be able to exchange information with an external system, and perform some actions with them such as pushing code to GitHub, booking a train, getting the weather forecast, or even controlling your house.

I also believe in standard and open source, and I really hope this standard will be adopted by all major actors such as OpenAI, Google, etc.

If all conditions are reunited, we will be able to do amazing things. At some point we could even avoid building a frontend. An API over MCP would be enough.

But we should not forget about skynet! 😀

Finally, since there is no official PHP SDK on the market, we would like to build one. Would it be interesting to try it?

(Read the full McpCommand code on github.com)

Ce que vous devez savoir sur les chaÃ®nes de caractÃ¨res

2024-12-04T14:42:00+01:00

Jouer avec les chaînes de caractères est certainement la première chose que l’on fait en tant que développeur. Qui n’a pas commencé sa carrière de dev par un “Hello World” ? Et pourtant, elles sont encore trop mal connues malgré tous les outils que nous possédons. Nous vous proposons aujourd’hui un récapitulatif de ce qu’est une chaîne de caractères, et des outils fournis par Symfony pour les manipuler.

Qu’est ce qu’une chaîne de caractères ? 🧐

Tout ce que vous lisez actuellement sont des chaînes de caractères. Tout ce que vous dites et entendez, et bien plus, se traduisent en chaînes de caractères. En revanche, pour l’ordinateur, il ne s’agit que d’une suite de 1 et de 0. Et nous allons nous intéresser à ce qu’il se passe entre les deux.

Un peu de vocabulaire…

Un glyphe est une représentation visuelle d’un élément d’écriture. Par exemple, a, A, 1 ou µ sont des glyphes, tout comme ~, n, ñ et même les emojis.

Un graphème est un symbole qui ne peut pas être divisé en unité plus petite, comme ~ ou n.

Un groupe de graphèmes rassemble plusieurs graphèmes et peut être vu comme un caractère. Par exemple, ñ est un groupe de graphèmes : c’est l’association de ~ et n.

Au passage, un graphème qui ne peut pas être utilisé seul, comme ~, des accents, ou encore une cédille, est appelé un diacritique (ça ne nous servira à rien ici, mais vous pourrez peut-être briller en société grâce à ça).

…et un peu d’histoire

Au commencement il y avait le binaire. Certains constructeurs décidèrent qu’une certaine séquence de 1 et de 0 signifiait “a”, mais cela n’était vrai que pour ce constructeur. Et comme au début de l’informatique, un document ne quittait pas le système sur lequel il était créé, cela ne posait pas de problème.

En 1961, l’ANSI se réunit et publie deux ans plus tard l’American Standard Code for Information Interchange, le Standard Américain pour l’Échange d’Information, ou ASCII pour les intimes, que nous retrouvons sur la fameuse table ASCII :

Les lettres étaient encodées sur 7 bits, ce qui offrait les 127 combinaisons ci-dessus. Notons qu’il n’y a en réalité que 95 caractères, les autres étant de la ponctuation, ou des caractères de contrôle. Il y en a même un, EM, pour prévenir s’il n’y a plus de bande magnétique !

Fort pratique pour les anglophones, ce choix est moins sympathique pour le reste du monde qui écrit avec de nombreux accents et lettres différentes.

En 1972, les processeurs 8 bits débarquent – merci IBM – et avec eux, la possibilité d’encoder non plus 127 caractères, mais 255 ! Pour rappel, un octet (byte en anglais) est un bloc de 8 bits, et chaque caractère est encodé sur un octet. Et 2 puissance 8, ça donne 256 ! Donc tout le monde fait un peu sa sauce avec les 128 caractères supplémentaires selon ses besoins et de très nombreuses variantes apparaissent.

Puis dans les années 90, le World Wide Web apparaît et des documents sont échangés à travers le monde… et à travers différents encodages. Puisque tout texte n’est qu’un ensemble de 0 et de 1, il n’y a absolument aucun moyen de deviner l’encodage du texte, ce qui rend vraiment visible toute erreur de décodage.

Par exemple, le é, en ASCII, sera encodé 11101001 mais en UTF-8, il sera encodé 11000011 10101001. Mais cette chaîne décodée en ASCII donnera… Ã© ! Ça ne vous rappelle rien ? Eh oui, le mojibake est né.

En 1991, la norme Unicode V1.0 fait son apparition ! Son nom est tiré de ses trois objectifs : Universel : correspond aux besoins linguistiques de toutes les langues et dialectes du monde; Uniforme : encodé sur une longueur fixe pour un accès plus efficace; Unique : chaque séquence de bits ne correspond qu’à une interprétation en caractères. Ce standard, encodé sur 16 bits, permet d’encoder 65 536 caractères ! Cette flexibilité le rend vite adopté par de nombreux langages de programmation tels que JavaScript, C, ou Java.

Point de code

Ou “Code point” en anglais. Il s’agit de la position numérique d’un caractère – glyphe, graphème, ou même diacritique – au sein d’un espace de codage bien défini. Mais il ne s’agit pas de sa valeur hexadécimale une fois encodé. Par exemple, le caractère é dans Unicode se situe au point de code U+000E9, mais sa valeur hexadécimale une fois encodé est C3A9. Si vous êtes perdus, n’hésitez pas à jouer avec des convertisseurs texte/binaire et binaire/décimal/hexadécimal.

Dans le standard Unicode, les points de code s’écrivent U (pour Unicode) suivis d’un + puis d’un numéro hexadécimal. Par exemple, le point de code de ñ est U+000F1. Mais ~ a aussi un point de code qui est le U+00303.

Wait, what? Le tilde a son propre point de code ?

Eh oui, il est possible de combiner plusieurs caractères. Par exemple ~ (U+00303) + n (U+0006E) donnera un caractère composé, ñ, mais qui sera différent de ñ (U+000F1), qui est un caractère à part entière.

L’arrivée d’UTF

Unicode introduit plusieurs encodages pour ces points de code : d’abord l’UTF-16, sur 16 bits, donc 2 octets. Mais on s’est rendu compte que 16 bits, c’était encore trop peu pour encoder tous les caractères du monde ! UTF-32 a donc été créé : un encodage sur 32 bits, donc 4 octets. Mais pour de nombreux caractères, les trois premiers octets n’étaient remplis que de zéros, ce qui crée une énorme perte de place en mémoire. Arrive alors UTF-8 dont chaque caractère peut être encodé sur 1 à 4 octets ! Le concept d’une taille variable est introduit, et cela permet de ne prendre que la taille nécessaire en mémoire.

À noter : UTF-8 assure une rétrocompatibilité avec l’ASCII pour tous les caractères dont le point de code est avant 128.

UTF-8 est maintenant largement adopté sur le Web, 98,3% quand j’écris ces lignes, et nous vous encourageons à n’utiliser que lui. Aujourd’hui, 149 186 caractères et environ 245 000 points de code peuvent être assignés sur un espace qui peut contenir jusqu’à 1 114 112 points de code différents.

Pour résumer ☕

Une chaîne de caractères peut être vue de trois manières : Sous forme d’un ensemble de graphèmes, de points de code ou d’octets.

L’approche du composant String de Symfony 🧩

Afin de pouvoir gérer ces trois différents aspects, le composant String nous propose de créer une chaîne de trois manières différentes :

new UnicodeString('Å');    	// ou u('Å')	// graphèmes
new CodePointString('Å');                	// points de code
new ByteString('Å');    	// ou b('Å')	// octets

La documentation de ce composant est très complète, n’hésitez pas à la consulter pour découvrir toutes les manipulations qu’il est possible d’effectuer avec le composant string !

$text = (new UnicodeString('This is a déjà-vu situation.'))
	->trimEnd('.')
	->replace('déjà-vu', 'jamais-vu')
	->append('!');
// $text = 'This is a jamais-vu situation!'

u('foo BAR')->upper(); // 'FOO BAR'
u('FOO Bar')->lower();  // 'foo bar'
u('Die O\'Brian Straße')->folded(); // "die o'brian strasse"

u('Foo: Bar-baz.')->camel(); // 'fooBarBaz'
u('Foo: Bar-baz.')->snake(); // 'foo_bar_baz'
u('Foo: Bar-baz.')->camel()->title(); // 'FooBarBaz'

u('abc')->indexOf('B');           	// null
u('abc')->ignoreCase()->indexOf('B'); // 1

u('hello')->append('world');  	// 'helloworld'
u('hello')->append(' ', 'world'); // 'hello world'

u('User')->ensureEnd('Controller');       	// 'UserController'
u('UserController')->ensureEnd('Controller'); // 'UserController'

u(' Lorem Ipsum ')->padBoth(20, '-');	// '--- Lorem Ipsum ----'
u('_.')->repeat(10);			// '_._._._._._._._._._.'
u('   Lorem Ipsum   ')->trim();			// 'Lorem Ipsum'
u('http://symfony.com')->replace('http://', 'https://');	// 'https://symfony.com'
u('Symfony is great')->slice(0, 7); 		// 'Symfony'
u('template_name.html.twig')->split('.');	// ['template_name', 'html', 'twig']

Certaines méthodes sont spécifiques à l’objet ByteString :

// returns TRUE if the string contents are valid UTF-8 contents
b('Lorem Ipsum')->isUtf8();	// true
b("\xc3\x28")->isUtf8();	// false

D’autres sont spécifiques aux objets CodePointString et UnicodeString, comme récupérer un point de code positionné à une certaine position dans la chaîne, ou convertir du texte en ascii :

u('नमस्ते')->codePointsAt(0); // न [2344]
u('नमस्ते')->codePointsAt(1); // म [2350]
u('नमस्ते')->codePointsAt(2); // स्ते [2360, 2381, 2340, 2375]

u('नमस्ते')->ascii();	// 'namaste'
u('さよなら')->ascii();	// 'sayonara'
u('спасибо')->ascii();	// 'spasibo'
u('🦄')->ascii();		// '?'

La méthode ->ascii() utilise la translittération – dont nous parlerons juste après – mais si vous avez besoin d’un slugger, utilisez plutôt ceci :

AsciiSlugger

L’AsciiSlugger de Symfony est un outil très utile qui permet simplement de transformer n’importe quelle chaîne en chaîne valide pour des URLs ou encore des noms de fichiers. Il s’utilise comme ceci :

$slugger = new AsciiSlugger();
$slug = $slugger->slug('Wôrķšƥáçè ~~sèťtïñğš~~', '/');
// $slug = 'Workspace/settings'

Mais si vous voulez un peu plus de paillettes dans votre code, vous pouvez transformer ce slugger en EmojiSlugger ! Ajoutez simplement l’option ->withEmoji(), choisissez une locale, et amusez-vous :

$slugger = $slugger→withEmoji();

$slug = $slugger→slug('a 😺, and a 🦁 go to 🏞️', '-', 'en');
// $slug = 'a-grinning-cat-and-a-lion-go-to-national-park';

$slug = $slugger→slug('un 😺, et un 🦁 vont au 🏞️', '-', 'fr');
// $slug = 'un-chat-qui-sourit-et-un-tete-de-lion-vont-au-parc-national';

Le concept de translittération 🌎

Avec l’arrivée d’internet, la question de l’internationalisation s’est rapidement posée. Tous les claviers ne possèdent pas les mêmes caractères, et pourtant, lorsque je recherche des artistes comme Eivør ou Rebūke dans ma playlist Spotify, je m’attends à les trouver en tapant simplement “Eivor” ou “Rebuke”. Convertir une chaîne en une autre similaire visuellement ou phonétiquement, c’est ce qu’on appelle la translittération.

Cette opération est particulièrement pratique avant d’effectuer un tri ou une opération d’indexation. En PHP natif, elle s’effectue comme ceci :

transliterator_transliterate(
'Any-Latin; Latin-ASCII; Lower()',
"A æ Übérmensch på høyeste nivå! И я люблю PHP! ﬁ"
);
// "a ae ubermensch pa hoyeste niva! i a lublu php! fi"

Le premier argument est une série d’instructions séparées par un point virgule. Ici on demande à traduire par n’importe quel caractère latin, en ASCII, et on passe tout en minuscules.

Le site decodeunicode.org, que j’apprécie beaucoup pour la quantité d’informations qu’il fournit, indique parfois les autres glyphes qui entrent dans la composition d’un graphème. Plus tôt, je vous parlais de ñ; sa page sur le site indique, entre autres, sa décomposition, c’est-à-dire les autres caractères qui le composent.

Homoglyphes

J’en profite pour aborder le concept d’homoglyphes : il s’agit de caractères particulièrement similaires visuellement ! Ceux-ci sont aussi visibles sur le site de decodeunicode. Le principe de la normalisation de composition ou de décomposition (passer de ñ à la combinaison de n et ~ et vice versa) permet de transformer des homoglyphes en caractères par défaut.

Cela a laissé la place à une faille de sécurité survenue chez Github il y a quelques années : il était possible de voler le compte de quelqu’un simplement en utilisant adresse mail visuellement similaire à la sienne ! Cela était dû au fait que l’adresse mail entrée dans le champ “mot de passe oublié” était normalisée avant d’être recherchée dans la base de données. Ainsi, pour attaquer mike@example.org, il suffisait d’entrer ｍｉᏦᎬ@example.org dans le champ. Le compte de mike était bien retrouvé, mais le token de récupération de mot de passe était ensuite généré et envoyé à ｍｉᏦᎬ ! L’attaquant n’avait alors plus qu’à se connecter avec le compte de mike et son nouveau mot de passe. Alors soyez vigilant.e.s avant d’utiliser la normalisation à tout va !

Si votre base de données est encodée en UTF-8, alors ce problème ne devrait pas se poser.

Un autre exemple d’attaque par homoglyphe est celui d’utilisation de noms de domaine visuellement similaires. Par exemple, certains attaquants ont créé le domaine www.airfrạnce.com. Si vous regardez bien, le a de France est en fait un a avec un point dessous (U+01EA1) ! Les attaquants envoyaient donc ce lien avec la promesse d’un billet d’avion à gagner et il était très compliqué pour les utilisateurs de voir la différence.

Aujourd’hui, ces URLs sont régulièrement traduit en “punycode” par les navigateurs et applications. Il s’agit d’une version sans accents et précédée de xn-- et dont les caractères spéciaux sont supprimés. Vous pouvez trouver plus de détails dans cet article.

En pratique : la taille d’une chaîne 🧮

Vous pensez que c’est facile ? Spoiler : oui, mais pas comme vous le pensiez !

Compter le nombre de caractères sur son site Web est une action très courante, qu’il s’agisse de vérifier la longueur d’un mot de passe, ou de compter les caractères d’un champ texte par exemple.

Pour un article très détaillé et technique sur le sujet, n’hésitez pas à lire It’s Not Wrong that "🤦🏼‍♂️".length == 7 de Henri Sivonen ; mais si vous avez la flemme, en voici un résumé qui ne s’intéresse qu’à la partie PHP.

En effet, d’un langage à l’autre, la taille de la chaîne de caractères 🤦🏼‍♂️ peut être 1, 5, 7 ou encore 17. Rien qu’en PHP, vous obtiendrez 17 avec strlen('🤦🏼‍♂️'); et 5 avec mb_strlen('🤦🏼‍♂️', 'UTF-8');. Vous vous en doutez, cela dépend de ce qu’on compte : des octets ? Des points de code ? Des graphèmes ?

Décomposons cet emoji pour comprendre ce qu’il se passe. Il est constitué de 5 caractères distincts : l’emoji facepalm, un modificateur de couleur de peau, ainsi qu’un modificateur de genre. À ces caractères s’ajoutent le “zero width joiner”, ou “jointure de taille zéro”, qui permet d’indiquer que les caractères se superposent, ainsi que le “variation selector” ou “sélecteur de variation” qui explicite le fait que l’on souhaite afficher un emoji coloré plutôt qu’un dingbat monochrome.

D’un langage à l’autre, les différents caractères qui composent un graphème sont enregistrés dans des “code units” ou unités de code qui contiennent plus ou moins d’octets.

Le tableau suivant décompose cet emoji, et pour chaque part, nous donne sa taille en unités de code et en octets.

Scalaire Unicode	Unités de code UTF-32	Unités de code UTF-16	Unités de code UTF-8	UTF-32 code octets	UTF-16 code octets	UTF-8 code octets
U+1F926 FACE PALM 🤦	1	2	4	4	4	4
U+1F3FC EMOJI MODIFIER FITZPATRICK TYPE-3 🏼	1	2	4	4	4	4
U+200D ZERO WIDTH JOINER	1	1	3	4	2	3
U+2642 MALE SIGN ♂	1	1	3	4	2	3
U+FE0F VARIATION SELECTOR-16	1	2	3	4	2	3
Total	5	7	17	20	14	17

Dans le cas d’un emoji, on s'attendra bien souvent à ce que son nombre de caractères soit égal à 1. On veut donc compter les graphèmes. Eh bien le composant String nous permet cette granularité :

(new ByteString('🤦🏼‍♂️'))->length();    	// 17 octets
(new CodePointString('🤦🏼‍♂️'))->length();	// 5 points de code
(new UnicodeString('🤦🏼‍♂️'))->length();	// 1 graphème

Et dans la base de données ? 💾

Petit point vocabulaire

Character set : Un set de caractères. Il définit l’encodage de chaque glyphe. Par exemple, utfmb4 est un set de caractères correspondant à l’UTF-8 dans les BDD MySQL. Collation : Une règle de tri des caractères les uns par rapport aux autres. Est-ce que a doit être rangé entre A et B ou plutôt après Z ? Par exemple, avec la collation utf8mb4_unicode_ci de MySQL, le ß, le double s allemand, sera considéré comme ss et œ est considéré comme oe. En revanche, avec la collation utf8mb4_general_ci, le ß est considéré comme un s simple et le œ est considéré comme un e.

Les différents sets de cractères

PostgeSQL c’est le bon élève de cette histoire : son set de caractère correspondant à UTF-8 se nomme sobrement UTF8, et se comporte bien comme tel : il est encodé sur 1 à 4 octets de 8 bits.

Chez Oracle, il faudra utiliser le set de caractères nommé AL32UTF8. Leur UTF8 correspond à la norme Unicode 3.0 mais n’est plus à jour aujourd’hui.

Chez MariaDB et MySQL, il faut utiliser utfmb4, et pas utf8 qui est encodé sur 3 octets. Vous pouvez lire cet article très intéressant, si vous souhaitez en apprendre plus sur l’existence de cet étrange set de caractères.

En terme de sécurité, ici aussi l’encodage a été source de problèmes. Lorsqu’on veut insérer un caractère dont la valeur est supérieure à 0xFFFF dans une colonne dont le charset est utf8, MySQL va tronquer la chaîne au niveau du caractère en question. Par exemple, si je veux insérer “Hello 👋 world 🌍 !”, seul “Hello ” sera inséré puisque l’emoji a pour valeur 0xF09F918B, qui est donc bien supérieure à 0xFFFF.

Ainsi, un attaquant peut s’inscrire sur un site dont l’inscription est restreinte par domaine simplement en ajoutant un emoji à la fin de la chaîne qu’il veut voir insérer en base. Par exemple, l’attaquant s’inscrit avec “attacker@gmail.com🍕@allowed-domain.com”. Le site effectue un check sur “@allowed-domain.com” et autorise l’inscription, mais seulement “attacker@gmail.com” !

C’est ici un exemple assez naïf, mais j’espère que vous faites des vérifications plus solides sur les mails de vos utilisateurs !

En tous cas nous vous encourageons à faire attention aux sets de caractères que vous utilisez.

Pour conclure

Éviter les erreurs d’encoding est particulièrement simple à notre époque, du moment que tout est configuré avec UTF-8. Symfony nous propose également des outils dédiés afin que nous puissions développer sans nous poser de questions. Alors plus d’excuses pour laisser traîner du mojibake !

Comment héberger de manière sécurisée du contenu statique ?

2024-11-28T14:42:00+01:00

Introduction

Je pars en voyage, tout est prêt : valises bouclées, papiers rangés, téléphone chargé. Mais une question me titille : que se passe-t-il si je perds mon téléphone ou que l'on me vole mes affaires ? Comment accéder à mes e-mails, mon compte Dropbox, mes codes de récupération pour les services protégés par une double authentification ?

Cette problématique, bien que rarement urgente, mérite d’être anticipée. Car si vos mots de passe suffisaient autrefois, la double authentification rend cette dépendance plus complexe. Alors, comment protéger efficacement ces informations sensibles tout en s'assurant qu'elles restent accessibles en cas de coup dur ?

Voyons ensemble comment créer une solution élégante et sécurisée pour répondre à ce besoin.

Une solution simple

Une première réponse pourrait consister à partager certains codes de récupération avec une personne de confiance. C'est simple, mais cela pose des défis :

Multiplicité des codes : si vous avez de nombreux comptes, cette solution devient difficile à gérer ;
Fiabilité en cas d’urgence : dans une situation stressante, il peut être compliqué de se souvenir à qui vous avez confié un code. De plus, les différences de fuseaux horaires peuvent rendre la communication difficile.

Une solution plus avancée

Une alternative serait de déployer une page HTML contenant tous vos codes de récupération. Vous pourriez l’héberger sur une plateforme gratuite comme GitHub Pages, Netlify ou Cloudflare. Mais cela soulève une question essentielle : comment sécuriser efficacement cette page ?

Chiffrer le contenu

La première idée est de chiffrer le contenu de la page HTML de manière symétrique (avec un mot de passe). Une fois stocké, le contenu serait accessible uniquement après avoir saisi le mot de passe.

C’est exactement ce que permet staticrypt. Cet outil en ligne de commande chiffre vos fichiers statiques en utilisant l’algorithme AES-256 via WebCrypto.

Le résultat est une page HTML qui :

demande un mot de passe via un formulaire ;
déchiffre le contenu directement dans le navigateur grâce à JavaScript.

Simple et robuste !

Héberger le contenu

Pour l’hébergement, GitHub Pages ou Netlify sont des choix évidents. Ces plateformes sont simples à utiliser et gratuites. Mais même si l’AES-256 est fiable, je reste inquiet à l’idée de stocker publiquement mes codes de récupération, même chiffrés. Est-ce que AES-256 sera toujours résistant aux attaques post-quantique ?

Pourquoi ? Parce qu’une faille découverte dans le futur pourrait compromettre la sécurité de ces données sensibles. Il faut donc ajouter une couche de protection supplémentaire : une authentification HTTP en amont de la page HTML chiffrée.

Sur GitHub Pages, cette fonctionnalité n’est pas disponible (surtout sur le plan gratuit). Heureusement, Cloudflare Workers offre une solution parfaite.

Cloudflare permet de déployer du code JavaScript à travers son CDN, ce qui rend facile l’ajout d’une authentification avant même de servir la page HTML. Ce code JavaScript n'est pas exécuté dans le navigateur, mais sur les serveurs de Cloudflare. Pour gagner du temps, je me suis inspiré de cet article de blog, qui détaille parfaitement le processus.

Automatisation avec Castor

Pour assembler ces briques, j’ai utilisé l’outil Castor :

Task castor build : génère les fichiers nécessaires grâce à Twig, ce qui facilite la gestion du HTML. Voici un extrait de la tâche castor :

$recoveryCodes = $twig->render('recovery-codes.html.twig', [
    'recovery_codes' => yaml_parse(file_get_contents($recoveryCodesFilename)),
]);
file_put_contents(__DIR__.'/var/tmp/recovery-codes.html', $recoveryCodes);
run(
    command: [
        __DIR__.'/node_modules/.bin/staticrypt',
        '--template', __DIR__.'/var/tmp/staticrypt.html',
        '--template-title', 'Recovery codes',
        '--config', 'false', // No need to store the salt, remember me is disabled
        '--remember', 'false', // Since data are sensitive, we don't want to remember the password
        ...(variable('defaultPassword') ? ['--short'] : []),
        '-d', 'dist/public',
        __DIR__.'/var/tmp/recovery-codes.html',
    ],
    context: context()
        ->withEnvironment([
            'STATICRYPT_PASSWORD' => variable('PASSWORD'),
        ])
);

Task castor deploy : déploie automatiquement le tout sur Cloudflare grâce à wrangler. Il vous faudra un compte au préalable et configurer deux variables d’environnement, ensuite castor s’occupe de tout.

En quelques commandes, tout est prêt ! 🎉

Conclusion

J’ai désormais une solution simple, gratuite, sans maintenance, pérenne, et sécurisée pour stocker du contenu sensible sur internet.

Première section : protégée par un mot de passe, elle peut contenir des documents importants (copie de passeport, permis de conduire, contacts d’urgence). Ce mot de passe peut être communiqué à mon entourage de confiance.
Deuxième section : réservée à mes données sensibles (codes de récupération, etc.), elle est chiffrée avec un mot de passe distinct que je conserve pour moi seul. Ce nouveau mot de passe n'est connu que de moi.

Parce que j’aime partager mes projets open source, celui-ci est déjà disponible sur GitHub, accompagné d’une démonstration partielle hébergée sur GitHub Pages.

Vers l’avenir

À l’avenir, j’aimerais que cette solution évolue pour gérer des scénarios encore plus critiques, comme le transfert d’informations en cas de décès.

Astuce : Si vous avez un compte GitHub, pensez à désigner un successeur. GitHub y a pensé, mais ce n’est pas le cas de tous les services (banques, assurances, etc.).

Enfin, il existe des algorithmes comme Shamir's Secret Sharing, permettant de chiffrer des documents et de les déchiffrer seulement si plusieurs personnes s’accordent. Je réfléchis à une intégration de cette technologie pour rendre le projet encore plus complet.

Écrire des assertions PHPUnit plus simples grâce au VarDumper

2024-11-20T15:42:00+01:00

Les tests unitaires sont une étape cruciale pour garantir la qualité de votre code, mais parfois, les répétitions peuvent devenir lassantes. Avez-vous déjà soupiré en enchaînant des appels à $this->assertXXX() pour valider des structures complexes ? Heureusement, il existe une solution élégante pour simplifier tout cela : le composant Symfony/VarDumper.

Voyons ensemble comment l'utiliser pour rendre vos tests plus concis et lisibles tout en conservant leur efficacité.

Un exemple concret

Imaginons que nous souhaitions tester certaines propriétés d’une classe comme celle-ci :

final readonly class MyObject
{
    public function __construct(
        public string $aPublicProperty = 'a public property',
        protected string $aProtectedProperty = 'a protected property',
        private string $aPrivateProperty = 'a private property',

        public string $anotherPublicProperty = 'another public property',
        protected string $anotherProtectedProperty = 'another protected property',
        private string $anotherPrivateProperty = 'another private property',
    ) {}
}

Lorsque vous dumpez un objet instancié avec ses valeurs par défaut, voici le résultat obtenu :

PhpunitVarDumper\MyObject^ {#325
  +aPublicProperty: "a public property"
  #aProtectedProperty: "a protected property"
  -aPrivateProperty: "a private property"
  +anotherPublicProperty: "another public property"
  #anotherProtectedProperty: "another protected property"
  -anotherPrivateProperty: "another private property"
}

Simplifier les tests

Traditionnellement, on utiliserait plusieurs appels à $this->assertSame() pour valider ces propriétés. Cependant, grâce à Symfony/VarDumper, nous pouvons alléger ce processus en utilisant une assertion sur le dump directement.

Commencez par installer le composant en mode développement :

composer require --dev symfony/var-dumper

Ensuite, importez le trait VarDumperTestTrait et utilisez la méthode assertDumpEquals() dans vos tests :

use PHPUnit\Framework\TestCase;
use PhpunitVarDumper\MyObject;
use Symfony\Component\VarDumper\Test\VarDumperTestTrait;

final class MyObjectTest extends TestCase
{
    use VarDumperTestTrait;

    public function test()
    {
        $myObject = new MyObject();

        $this->assertDumpEquals(
            <<<'DUMP'
            PhpunitVarDumper\MyObject {
              +aPublicProperty: "a public property"
              #aProtectedProperty: "a protected property"
              -aPrivateProperty: "a private property"
              +anotherPublicProperty: "another public property"
              #anotherProtectedProperty: "another protected property"
              -anotherPrivateProperty: "another private property"
            }
            DUMP,
            $myObject,
        );
    }
}

N’est-ce pas plus clair et élégant ? 🎉

Aller plus loin avec les Casters

Dans certains cas, toutes les propriétés d’un objet ne sont pas pertinentes pour vos tests, ou vous ne souhaitez pas les mettre à jour à chaque modification de la classe. C’est ici que les casters entrent en jeu.

Un caster est une fonction de rappel qui personnalise la représentation d’un objet dumpé. Elle prend en paramètre :

L’objet en cours de dump ;
Un tableau représentant l’état de l’objet ;
(d'autres paramètres que nous n'utilisons pas ici).

Pour ajouter un caster, utilisez la méthode setUpVarDumper() dans votre test :

final class MyObjectTest extends TestCase
{
    use VarDumperTestTrait;

    protected function setUp(): void
    {
        $this->setUpVarDumper(
            [
                MyObject::class => static function (MyObject $myObject, array $a): array {
                    return $a;
                },
            ],
        );
    }
}

Pour le moment, notre caster ne sert à rien. Observons donc ce que contient la variable $a :

^ array:6 [
  "aPublicProperty" => "a public property"
  "\x00*\x00aProtectedProperty" => "a protected property"
  "\x00PhpunitVarDumper\MyObject\x00aPrivateProperty" => "a private property"
  "anotherPublicProperty" => "another public property"
  "\x00*\x00anotherProtectedProperty" => "another protected property"
  "\x00PhpunitVarDumper\MyObject\x00anotherPrivateProperty" => "another private property"
]

Si vous avez déjà joué avec PHP et ses mécanismes de sérialisation, vous ne devriez pas être perdu. Sinon une petite explication s’impose :

Chaque clé représente une propriété de l’objet.
Les notations varient en fonction de la visibilité de la propriété :
1. Pour une propriété publique, son nom apparaît directement en clair, comme "aPublicProperty".
2. Pour une propriété protégée, son nom est précédé par le préfixe spécial \x00*\x00, qui signale sa visibilité restreinte.
3. Pour une propriété privée, le préfixe indique son contexte de déclaration : \x00[NomDeLaClasse]\x00. Ici, cela donne par exemple \x00PhpunitVarDumper\MyObject\x00aPrivateProperty.

Ces notations un peu cryptiques peuvent sembler complexes à première vue. Heureusement, Symfony fournit des constantes pour les manipuler plus facilement, comme Caster::PREFIX_PROTECTED ou Caster::PATTERN_PRIVATE. Utilisons-les pour simplifier notre code de caster :

use Symfony\Component\VarDumper\Caster\Caster;

protected function setUp(): void
{
    $this->setUpVarDumper(
        [
            MyObject::class => static function (MyObject $myObject, array $a) {
                unset(
                    $a['anotherPublicProperty'],
                    $a[Caster::PREFIX_PROTECTED.'anotherProtectedProperty'],
                    $a[sprintf(Caster::PATTERN_PRIVATE, MyObject::class, 'anotherPrivateProperty')],
                );

                return $a;
            },
        ],
        AbstractDumper::DUMP_LIGHT_ARRAY,
    );
}

Ce caster permet de supprimer les propriétés non pertinentes. Le test devient alors :

public function test()
{
    $myObject = new MyObject();

    $this->assertDumpEquals(
        <<<'DUMP'
        PhpunitVarDumper\MyObject {
            +aPublicProperty: "a public property"
            #aProtectedProperty: "a protected property"
            -aPrivateProperty: "a private property"
        }
        DUMP,
        $myObject,
    );
}

En cas d’erreur, PHPUnit affiche un diff très lisible, ce qui facilite le debug :

1) PhpunitVarDumper\Tests\MyObjectTest::test
Failed asserting that two strings are identical.
--- Expected
+++ Actual
@@ @@
 'PhpunitVarDumper\MyObject {
-  +aPublicProperty: "Hello you!"
+  +aPublicProperty: "a public property"
   #aProtectedProperty: "a protected property"
   -aPrivateProperty: "a private property"
 }'

Quelques astuces supplémentaires

Affichage léger des tableaux Utilisez AbstractDumper::DUMP_LIGHT_ARRAY comme deuxième paramètre de setUpVarDumper() pour des tableaux plus compacts.
```
-array:3 [
-  0 => "a"
-  1 => "b"
-  2 => "c"
+[
+  "a"
+  "b"
+  "c"
 ]
```
Gestion des valeurs dynamiques Préférez un caster à assertDumpMatchesFormat(), car les diff générés avec des formats sont souvent difficiles à lire.

Conclusion

Le composant VarDumper est un allié précieux, tant pour le débogage que pour simplifier vos tests. Grâce à lui, vous gagnez en clarté et en efficacité.

Alors, dites adieu aux assertions fastidieuses, et concentrez-vous sur ce qui compte vraiment : la qualité de votre code. 🎉

BDX I/O au pays du vin : notre retour sur l'édition 2024

2024-11-19T09:42:00+01:00

Pour la première fois, nous nous sommes rendus à la conférence BDX I/O au Palais des Congrès de Bordeaux. Cette conférence existe depuis 2014 et a rassemblé plus de 1000 participants pour cette 9ème édition.

Cette année, le thème était l'IA. Marie-Alice Blete a lancé la journée avec un talk très intéressant appelé : "LLMs, entre fantasme et réalité - le point de vue d'une dev passée de l'autre côté".

En posant un autre regard sur les chiffres annoncés en grande fanfare par des acteurs de l'IA, elle remet la réalité au centre. Par exemple, il a été annoncé que les développeurs qui utilisent une IA pour coder font 25% de Pull Request en plus. Cependant, un chiffre moins communiqué est que la qualité globale de ces PRs a reculé, le code produit est considéré moins maintenable. Loin de l'euphorie, son regard pragmatique sur l'IAa été une introduction parfaite à cette journée.

Tout au long de la journée nous avons assisté à différents talks autour de ce sujet. Les enjeux d’une IA plus éco responsable nous ont été présentés. En effet, cette technologie a un bilan carbone très élevé et les entraînements des modèles d’IA sont voraces en énergie. Il a été démontré par exemple qu’une requête ChatGPT équivaut à 60 recherches Google. De plus, nous remarquons fréquemment, sur les sites que nous exploitons, d'importantes hausses de trafic sur certaines pages qui, après analyse, proviennent de bots qui collectent des données d'entraînement pour des modèles d'IA. Au-delà des questions légitimes de propriété intellectuelle, cela nous confronte souvent à deux problématiques : d'abord, cela crée de la charge en plus sur les infrastructures Web et, ensuite, cela pose la question de la consommation de ressources serveur pour cet objectif discutable. On peut toutefois noter qu'avec redirection.io, il est facilement possible de bloquer ces bots IA, si besoin.

Nous avons également été sensibilisés sur le sujet de l’IA et du Handicap. Elles nous ont donné leur constat sur les avancées dans le domaine et nous ont partagé leur craintes par rapport aux mauvaises représentations induites par certaines IA qui vont préférer mettre de côté les "valeurs aberrantes" et créer une forme d’exclusion.

Retrouvez les vidéos des conférences :

Découvrons ensemble la relève de l'observabilité avec les logs et les traces : Quickwit par Idriss Neumann

Les logs, les métriques et les traces sont les 3 piliers du monitoring applicatif. L'observabilité de sa plateforme est un point essentiel pour garantir la stabilité de son site dans le temps. Bien que nous soyons très friands de Datadog, nous surveillons beaucoup ce qu'il se passe autour d'OpenTelemetry.

Installer et maintenir Datadog représente un coût quasi nul, mais c’est un service qui peut vite coûter cher quand le nombre de serveurs ou le volume de données à traiter augmente. On peut préférer une alternative auto hébergée, pour des raisons de sécurité, ou parce que c’est une association où le temps des bénévoles est en plus grande quantité que les euros (cf. notre retour sur la conférence des Restos du Coeur, où Quickwit est employé).

Le choix le plus répandu dans ce cas, est la stack ELK, sur laquelle nous avons pas mal d'expérience. Dans ce cas, le souci est la gestion du stockage longue durée des logs, qui peuvent vite représenter un volume conséquent.

Quickwit se démarque en stockant ses données sur un object storage (type AWS S3 ou un cellar OVH / Clever Cloud). Ces stockages coûtent plusieurs centaines de fois moins cher que des disques traditionnels tout en assurant un stockage redondé et accessible (au dépend de la bande passante de sortie, souvent payante). Lire de la données sur un S3 est cependant un peu plus lent qu’un disque réseau, Quickwit indique compenser cette latence par une implémentation d’Apache Lucene - le moteur d'indexation/recherche utilisé par Elasticsearch - en Rust.

Pour la partie UI, ils se reposent sur les traditionnels Grafana / Jaeger.

Une autre alternative à étudier pour de l’auto hébergement semble être Signoz.io qui lui s’appuie sur Clickhouse - que nous utilisons beaucoup pour redirection.io - et une UI maison qui semble de haute qualité.

Un chatGPT sur vos propres données : comment ça marche ? par Hugo Vassard

Hugo Vassard nous a présenté avec brio comment concevoir un RAG sur ses propres données. À l'aide d'un exemple concret, il nous explique ce qu'est la vectorisation, les embeds, les chunks, ou encore les outils du type LangChain, …

Si c'est quelque chose qui vous intéresse, nous vous conseillons de lire l'article de Loïck sur la construction d'un chatbot spécialisé sur la documentation de notre task runner Castor.

La vidéo de la conférence est également disponible.

HTMX, où le retour de l'AJAX dans le développement Web par Stéphane Trebel

En Javascript, on passe beaucoup de temps à réinventer la roue. Tout ça pour créer des pages web de plus en plus grosses… Stéphane Trebel nous a présenté plusieurs cas d’utilisation de la librairie Htmx dans une conférence très dynamique. De l’infinite scroll en quelques lignes à la captation et la gestion d’erreurs simplifiée les possibilités ont l’air nombreuses et le code très clair et moins éparpillé. D’après lui, “Htmx c’est ce que le html aurait du devenir si on n'était pas passés en tout JS”.

Pour retrouver tous ses exemples, il suffit d’aller faire un tour sur son dépôt Github et la vidéo de la conférence.

Les 20 minutes de Typescript les plus rentables de votre vie ! par Aurélien Loyer et Delphin Aubin

Cette conférence était un ensemble de très bons conseils sur l’écosystème Typescript, nous retenons :

Une librairie pour passer en strict:true par étape ;
Les types guards (connaître le type actuel de notre valeur dans un contexte) ;
L’utilisation du type never pour détecter les cas manquants ;
La syntaxe en template string dans un type template littérals.

Et si tous ces concepts vous interpellent voici les slides de la conférence et la vidéo.

Comment nous avons transformé les Restos du Cœur en Cloud Provider ? par Julien Briault

Amazon a créé AWS car la logistique est très consommateur en applications diverses et en ressources.

Les Restos du Cœur sont dans la logistique également, et même dans la logistique compliquée : la nourriture (chaîne du froid, date de péremption, …). De plus, c'est une association qui tourne grâce à des bénévoles et où 1€ dépensé = 1 repas distribué en moins.

Une équipe d'admin sys et devops a réussi a rassembler de nombreux dons de matériels informatiques, beaucoup de connaissances et une tonne d'heures de bénévolat pour mettre en place un « cloud provider » à destination de la centaine d'antennes de l'association.

Tout un tas de noms connus et inconnus, avec pour objectifs : stabilité et gains financiers. On retrouve donc du Canonical Metal as a Service, Kubernetes, OpenStack. La plateforme permet même aux antennes de créer un cluster Kubernetes à la demande, donc il y a du Kubernetes dans OpenStack sur Kubernetes !

Les bénévoles des Restos du Cœur recrutent et c'est un très très bon moyen d'apprendre auprès de devops super contents et motivés.

Vous pouvez regarder la construction d'un cloud provider sur Youtube.

Vivement 2025

Nous avons beaucoup apprécié notre journée à BDX I/O. Avec 7 salles en parallèle, le choix peut être parfois difficile, mais toutes les conférences ont été de bonne qualité. Heureusement, toutes les captations vidéo sont disponibles sur la chaine Youtube de BDX I/O pour voir les conférences que nous avons pu louper.

Et, le plus important, le repas du midi était très bien : un buffet facile d'accès et bien garni !

BDX I/O, on se revoit l'année prochaine !

A la découverte des lazy proxy et lazy ghost objets de PHP 8.4

2024-10-28T10:42:00+01:00

Parmi toutes les nouvelles fonctionnalités de PHP 8.4, nous souhaitions vous faire découvrir les différents usages de la RFC "Lazy Objects". Cette RFC a été conduite par Arnaud Le Blanc, contributeur au cœur de PHP, et Nicolas Grekas, contributeur principal de Symfony.

Que signifie Lazy Loading ?

En informatique - mais pas uniquement, 👋 la procrastination - nous aimons délayer au plus tard possible l'utilisation de ressources. C'est-à-dire que nous souhaitons économiser au maximum des cycles CPU, de la consommation de mémoire, des IO tant que nous n'en avons pas besoin.

Prenons un exemple simple : sur une page web très longue, il est inutile de charger toutes les images dès l'ouverture. Il est probable que l'utilisateur ne scrolle jamais jusqu'en bas. En retardant le chargement des images, nous évitons plusieurs requêtes HTTP, ce qui allège le réseau.

C'est là qu'intervient le terme lazy. On reporte une tâche à plus tard. Par exemple, on ne charge les images que si l'utilisateur commence à faire défiler la page.

Dans cet article, nous allons voir ce que PHP 8.4 nous propose pour rendre notre code lazy.

Un peu d'histoire

Il n'y avait pas besoin d'attendre PHP 8.4 pour avoir des objets lazy. Nous pouvons déjà le faire dans notre propre code :

final readonly class CartRepository
{
    private Redis $redis;

    public function __construct(
        private string $host,
    ) {
    }

    public function isCartExpired(Cart $cart): bool
    {
        // de la logique qui n'a pas besoin de $this->redis

        return true;
    }

    public function save(Cart $cart)
    {
        $this->redis()->hMSet($cart->id, $cart->toArray());
    }

    public function get(string $cartId): Cart
    {
        return Cart::FromArray(...$this->redis()->hGetAll($cartId));
    }

    private function redis(): \Redis
    {
        if (isset($this->redis)) {
            return $this->redis;
        }

        $this->redis = new \Redis();
        $this->redis->connect($this->host);

        return $this->redis;
    }
}

Dans la classe CartRepository, la connexion au serveur Redis est ouverte uniquement lorsque le code en a réellement besoin. Un appel à la méthode isCartExpired() n'ouvrira pas la connexion, contrairement aux méthodes save() ou get().

Bien que fonctionnel, ce genre de code est pénible à écrire, source de discussions, et n’apporte pas beaucoup de valeur ajoutée au produit.

C’est pourquoi des bibliothèques ont vu le jour pour simplifier l’écriture de ce type de code. On peut citer :

FriendsOfPHP/proxy-manager-lts, un fork de Ocramius/ProxyManager qui n'est plus vraiment maintenue ;
symfony/var-exporter, une réécriture complète du premier.

Baptiste a d’ailleurs écrit un article sur l’utilisation de symfony/var-exporter.

Cependant, maintenir de telles bibliothèques en PHP est complexe. Certaines choses ne peuvent pas être faites en PHP pur, et il existe des cas où ces bibliothèques ne fonctionnent pas en raison de limitations techniques.

C’est pourquoi Nicolas et Arnaud ont travaillé ensemble pour intégrer ces fonctionnalités directement dans le cœur de PHP. Merci à eux 💛

Qu'est-ce qu'un lazy object ?

Lorsque vous souhaitez rendre un objet lazy, disons une instance de MyClass, PHP crée un proxy qui a la même signature que MyClass. Vu de l'extérieur, rien ne distingue ce proxy d'un objet classique. C’est nécessaire pour respecter les types des arguments ou propriétés en PHP.

Le lazy object se comporte exactement comme l’objet réel. Toutefois, au premier accès à l'une de ses propriétés non initialisées, le lazy loading se déclenche :

class MyClass
{
    public Deps $deps;

    public function greet()
    {
        return 'Hello 👋';
    }
}

//  Nous verrons comment faire un lazy objet plus tard
$myObject = create_lazy_object();

// return true
$myObject instanceof MyClass;

// Le lazy loading n'est pas déclenché car greet n'a pas besoin de `$deps`
echo $myObject->greet();

// Le lazy loading est déclenché ici
$myObject->deps;

Quand utiliser du lazy loading ?

Une question fréquente lors de nos formations est :

Pourquoi ne pas activer le lazy loading partout ?

Comme souvent, une fonctionnalité a un coût. Activer le lazy loading ralentit l'instanciation de la classe. Il faut donc trouver le juste milieu entre instancier toutes les dépendances ou rendre la classe lazy.

Dans l'exemple précédent, nous avons fait un petit benchmark entre une instanciation classique (direct) et une instanciation d’un objet lazy (lazy). Dans chaque cas, nous récupérons la dépendance :

direct   0.141μs (±2.09%)
lazy     0.434μs (±2.84%)

Il n’y a pas de solution parfaite. Si une classe utilise toujours ses dépendances, il n’y a aucune raison d’activer le lazy loading. Cependant, si une classe a une dépendance qui effectue une requête SQL, la question mérite d’être posée.

C’est d’ailleurs l’une des utilisations classiques du lazy loading. Doctrine ORM l'utilise largement. Dès que notre code a besoin de la propriété d'une relation, Doctrine exécute une requête SQL pour récupérer cette relation :

class Category
{
    public string $name;
}

class Page
{
    public function __construct(
        public Category $category
    ) {
    }
}

// Une requête SQL pour récupérer la page avec l'ID 12345
$page = $pageRepository->find(12345);

// Une autre requête SQL pour récupérer la catégorie associée
$page->category->name;

Ici, $page->category est un lazy object.

Un autre cas d’utilisation est celui des services lazy dans Symfony :

class Foo
{
    public function __construct(
        #[Autowire(lazy: true)]
        private Bar $bar
    ) {
    }
}

Tant que la propriété $this->bar n’est pas utilisée, elle n’est pas instanciée.

Il existe une méthode plus globale :

#[Autoconfigure(lazy: true)]
class Bar
{
}

Ici, tous les services dépendant de Bar recevront un proxy. La classe Bar ne sera instanciée qu'au moment d'un appel sur ses propriétés ou méthodes.

Les frameworks et bibliothèques adopteront sûrement rapidement cette nouveauté de PHP 8.4. Vous n’aurez probablement pas à l'utiliser directement, mais il est toujours intéressant de comprendre comment cela fonctionne.

Comment faire un lazy proxy avec PHP 8.4 ?

Étudions ensemble le code suivant :

final readonly class Client
{
    public function __construct(
        private string $a,
        private string $very,
        private string $long,
        private string $list,
        private string $of,
        private string $constructor,
        private string $argument,
        private string $userAgent,
    ) {
    }

    public function fetch(int $id): array
    {
        // Ici, on imagine faire un appel HTTP vers une API distante
        // Et nous aurons besoin de certains dépendance de la class client
        $this->userAgent;

        return [
            'id' => $id,
            'name' => 'John Doe',
        ];
    }

    public function getName(): string
    {
        return 'The Super API Client';
    }
}

final readonly class UserRepository
{
    public function __construct(
        public Client $client,
    ) {
    }

    public function find(int $id): array
    {
        return $this->client->fetch($id);
    }

    public function isUserEnabled(User $user): void
    {
        // de la logique qui n'a pas besoin de $this->client

        return true;
    }
}

Nous avons deux classes :

Client effectue des requêtes HTTP vers une API ;
UserRepository expose des méthodes pour récupérer des utilisateurs.

L’instanciation de Client est complexe car elle nécessite de nombreux paramètres coûteux à obtenir. Rendons cette classe lazy grâce à la réflexion, qui est l’unique moyen de créer des objets lazy :

$reflector = new ReflectionClass(Client::class);

$client = $reflector->newLazyProxy(function (): Client {
    // Instanciation du vrai Client
    // Ce code ne sera appelé uniquement au moment où une propriété du **Client** sera utilisé
    return new Client(
        'a',
        'very',
        'long',
        'list',
        'of',
        'constructor',
        'argument',
        'Mozilla/5.0',
    );
});

Et voilà 🎉, ce n'était pas compliqué ?

Nous pouvons maintenant utiliser ce lazy proxy dans notre repository :

$repository = new UserRepository($client);

// A ce moment de l'exécution du code, le vrai Client n'a pas été instancié
$repository->isUserEnabled($user);

// A ce moment de l'exécution du code, le vrai Client n'a toujours pas été instancié
dump($repository->client->getName());

// Mais ce code va déclencher l'instantiation du vrai Client
dump($repository->find(42));

// Affichera :
// ^ array:2 [
//   "id" => 42
//   "name" => "John Doe"
// ]

Vous pouvez voir ce code en action sur 3v4l.org.

Le titre de l'article mentionne lazy ghost, mais nous n'en avons toujours pas parlé ! Il est temps de remédier à ça.

Les Ghost Objects sont des lazy objects d’un type un peu différent. Au lieu d'instancier l'objet, ils se concentrent sur l'initialisation de ses propriétés.

Cela peut être utile lorsque vous ne souhaitez pas lancer une logique complexe au début, mais juste initialiser une partie de votre objet.

Comment faire un lazy ghost ?

Cette fois-ci, étudions un code un peu différent :

final readonly class Post
{
    public int $id;
    public string $name;
    public string $email;

    public function greet(): string
    {
        return "Hello 👋";
    }
}

final readonly class PostRepository
{
    public function find(int $id): Post
    {
        // Fait des appels à la base de données
    }
}

Nous avons deux classes :

Post est un DTO qui contient des données
PostRepository est une classe qui expose des méthodes pour récupérer des posts.

Contrairement au chapitre précédent, nous n'avons pas un service que nous voulons rendre lazy. Ici, nous voulons rendre une instance de Post lazy. C'est-à-dire que nous voulons retourner une instance de Post de la méthode PostRepository::find(), mais que la requête SQL soit retardée jusqu'à l'utilisation d'une propriété de l'instance Post.

Implémentons la méthode find() ensemble, avec des commentaires dans le code :

final readonly class PostRepository
{
    private ReflectionClass $reflector;

    public function __construct()
    {
        // Nous aurons besoin de la réflexion, alors stockons immédiatement une instance dans le repository
        $this->reflector = new ReflectionClass(Post::class);
    }

    public function find(int $id): Post
    {
        // Contrairement à newLazyProxy(), nous recevons une instance de Post, mais entièrement vide
        $entity = $this->reflector->newLazyGhost(function (Post $entity) use ($id): void {
            // Nous récupérons les données stockées en base de données
            $data = $this->loadFromDatabase($id);

            // Nous assignons les données aux différentes propriétés
            $this->reflector->getProperty('name')->setValue($entity, $data['name']);
            $this->reflector->getProperty('email')->setValue($entity, $data['email']);
        });

        // Comme nous connaissons déjà l'ID du post, nous pouvons le définir dans la classe directement.
        // Un appel à cette propriété ne déclenchera pas le chargement
        $this->reflector->getProperty('id')->setRawValueWithoutLazyInitialization($entity, $id);

        return $entity;
    }

    private function loadFromDatabase(int $id): array
    {
        // Simule une requête à la base de données
        return [
            'name' => 'John Doe',
            'email' => 'john.doe@example.com',
        ];
    }
}

Et voilà 🎉, ce n'était pas compliqué ?

Nous pouvons maintenant utiliser ce ghost object dans notre code :

$em = new PostRepository();
$post = $em->find(42);

// À ce moment, la récupération en base de données n'a pas été effectuée
dump($post);
// Affiche
// ^ Post^ {#6
//   +id: 42
//   +name: ? string
//   +email: ? string
// }

// À ce moment, la récupération en base de données n'a toujours pas été effectuée
dump($post->greet());

// Mais ce code va déclencher la récupération en base de données
$post->email;

dump($post);
// Affiche
// ^ Post^ {#12
//   +id: 42
//   +name: "John Doe"
//   +email: "john.doe@example.com"
// }

Vous pouvez voir ce code en action sur 3v4l.org.

Un use case plus réaliste ?

Les deux exemples précédents ne sont pas très réalistes. En général, vous n'aurez pas à écrire ce code, car votre framework préféré, ainsi que votre ORM, le feront pour vous.

Nous avons réfléchi à un cas d'usage un peu plus réaliste. Laissez-nous poser le contexte. Sur un site à très fort trafic, il est peu recommandé de stocker les paniers dans une base de données, qui se remplirait trop vite, devenant trop gourmande en ressources et augmentant considérablement la facture. Une solution couramment utilisée est le stockage du panier dans Redis.

Dans l'exemple suivant, nous avons une classe Cart avec un id et une collection de Product. Ces produits sont néanmoins stockés en base de données, avec Doctrine. Pour optimiser l'application, nous ne voulons pas récupérer les produits tant qu'ils ne sont pas affichés. Souvent, le total ainsi que le nombre d'éléments sont suffisants.

Observons nos objets métier :

final readonly class Product
{
    public function __construct(
        public string $id,
        public string $name,
        public string $description,
        public int $price = 10,
    ) {
    }
}

final class Cart
{
    /**
     * @param Product[] $products
     */
    public function __construct(
        public string $id,
        public array $products = [],
        public int $total = 0,
        public int $quantity = 0,
    ) {
    }

    public function addProduct(Product $product): void
    {
        $this->products[] = $product;
        $this->quantity++;
        $this->total += $product->price;
    }
}

final readonly class ProductRepository
{
    public function find(string $id): Product
    {
        // Simule le chargement depuis la base de données
        return new Product($id, "product-$id", "description-$id");
    }

    public function findByIds(array $ids): array
    {
        // Simule le chargement depuis la base de données
        $products = [];
        foreach ($ids as $id) {
            $products[] = $this->find($id);
        }

        return $products;
    }
}

Rien de nouveau ici. Nous voulons utiliser ce type de code :

$productRepository = new ProductRepository();
$repository = new CartRepository($productRepository);

$cart = new Cart('#cart-01');
$cart->addProduct($productRepository->find('1'));
$cart->addProduct($productRepository->find('2'));
$cart->addProduct($productRepository->find('3'));

// C'est cette chaîne qui sera stockée dans Redis
$serialized = $repository->serialize($cart);

// Une nouvelle requête HTTP arrive

// On récupère la chaîne depuis Redis, et on hydrate le panier
// À ce moment, aucune requête SQL n'a été effectuée
$newCart = $repository->unserialize($serialized);

// À ce moment, toujours aucune requête SQL n'a été effectuée
dump($newCart->total);

// Mais ce code va déclencher une requête SQL
$newCart->products;

Maintenant que nous avons vu les objets métier ainsi que leur utilisation, voyons comment coder le CartRepository :

final readonly class CartRepository
{
    private ReflectionClass $reflector;

    public function __construct(
        private ProductRepository $productRepository,
    ) {
        $this->reflector = new ReflectionClass(Cart::class);
    }

    public function serialize(Cart $cart): string
    {
        return json_encode([
            'id' => $cart->id,
            'products' => array_column($cart->products, 'id'),
            'total' => $cart->total,
            'quantity' => $cart->quantity,
        ]);
    }

    public function unserialize(string $data): Cart
    {
        $previousCart = json_decode($data, true);

        $newCart = $this->reflector->newLazyGhost(function(Cart $newCart) use ($previousCart): void {
            $products = $this->productRepository->findByIds($previousCart['products']);
            $this->reflector->getProperty('products')->setValue($newCart, $products);
        });

        $this->reflector->getProperty('id')->setRawValueWithoutLazyInitialization($newCart, $previousCart['id']);
        $this->reflector->getProperty('total')->setRawValueWithoutLazyInitialization($newCart, $previousCart['total']);
        $this->reflector->getProperty('quantity')->setRawValueWithoutLazyInitialization($newCart, $previousCart['quantity']);

        return $newCart;
    }
}

Nous avons une méthode serialize qui nous permet d'obtenir une représentation sous forme de chaîne de notre panier. C'est elle qui sera stockée dans Redis. Elle ressemble à ceci :

"{"id":"#cart-01","products":["1","2","3"],"total":30,"quantity":3}"

Quand une nouvelle requête HTTP arrive, il faut désérialiser la représentation et reconstruire le panier. Comme dans le chapitre précédent, nous utilisons la réflexion.

Comme d'habitude, retrouvez le code en action ici.

Conclusion

Les lazy ghosts et lazy proxies sont vraiment très intéressants. Avec une API simple, ils permettent de retarder l'instanciation de nos objets jusqu'à ce que nous en ayons vraiment besoin. L'API est assez intuitive et naturelle à prendre en main. Cependant, il est important de s'exercer un peu pour en comprendre les subtilités. Cet article n'a pas pu toutes les couvrir, ni montrer toutes les options disponibles. Nous vous invitons à lire la RFC pour en apprendre plus.

Quelques points pourraient encore être améliorés :

La possibilité de rendre une seule propriété lazy, et non toute la classe ;
La possibilité de rendre un objet déjà existant lazy, de sorte que si une propriété non initialisée est appelée, l'initialiseur soit déclenché.

PHP 8.4 n'étant toujours pas officiellement sorti, cette fonctionnalité n'est probablement pas encore utilisable. Mais nous sommes certains qu'elle le sera très rapidement par Doctrine et Symfony (Nicolas l'a conçue pour cela).

Construire un chatbot spécialisé sur vos données grâce à l'IA générative et PHP

2024-10-24T11:42:00+02:00

Utilisée pour rédiger n'importe quel type de contenus, pour faire des résumés ou encore intégrée à nos outils de développement, l'IA, et en particulier l'IA générative, a trouvé sa place dans bon nombre de secteurs. Basée sur des LLM entraînés sur des quantités astronomiques de documents divers et variés, ces IA sont capables de comprendre et répondre à la plupart des questions qui leur sont posées. Ce qui ne les empêche cependant pas de donner des réponses erronées ou imprécises dans beaucoup de situations.

Prenons l'exemple de notre projet Castor et sa documentation en ligne et demandons à ChatGPT le rôle de la fonction run() :

Même s'il comprend à peu près de quoi nous parlons, l'explication et l'exemple fournis ne sont pas corrects : la fonction line() n'existe tout simplement pas. ChatGPT n'a pas été entraîné spécifiquement sur la documentation de Castor mais a malgré tout "improvisé" une réponse.

Heureusement, il existe un moyen de forcer ce genre d'IA à être plus pertinente sur des domaines précis, sans avoir à dépenser du temps, ni d'argent à entraîner nos propres modèles de LLM. C'est notamment le principe de fonctionnement des Retrieval-Augmented Generation, abrégés RAG.

Qu'est-ce qu'un RAG ?

Bien qu'un modèle de langage (LLM) soit entraîné sur une vaste quantité de documents, il ne peut jamais être constamment à jour ni pertinent sur tous les sujets pour plusieurs raisons :

son entraînement prend souvent du temps ;
les documents en ligne (sur lesquels ils sont entraînés) changent régulièrement ;
le modèle n'a pas accès à toutes les informations du monde (et heureusement).

Dans cet article, nous utiliserons la documentation de Castor comme exemple. Mais imaginez avoir une IA capable de répondre à vos questions sur n'importe quel outil open source ou encore sur votre documentation interne du fonctionnement de votre entreprise.

C'est là qu'intervient le concept de RAG (Retrieval-Augmented Generation). Il permet de découper le processus de génération de réponses en deux étapes distinctes :

La récupération 🔎

Lorsque l'utilisateur va saisir un message, nous allons nous occuper nous-mêmes de rechercher les documents pertinents pour lui répondre. Cette recherche pourrait se faire en faisant une simple recherche de mots-clefs dans notre ensemble de documents, par exemple avec Elasticsearch. Mais cela reste assez basique et les résultats peu satisfaisants. À la place, nous allons effectuer une recherche vectorielle dans notre corpus de documents. Cette idée peut faire peur au premier abord mais elle n'est pas très compliquée à appréhender. Voyons maintenant comment cela fonctionne.

Dans un premier temps, nous allons transformer chaque document en vecteurs. Ce vecteur est un objet mathématique qui permet de représenter le contexte et la sémantique du document en question. Ainsi, deux documents qui parlent d'un sujet assez similaire auront des vecteurs assez proches dans l'espace vectoriel rattaché.

Exemple de représentation de documents dans un espace vectoriel à trois dimensions.

Dans cet exemple simplifié, on voit que les deux chapitres de la documentation à propos des fonctions run() et capture() sont assez proches, et plutôt éloignés du chapitre concernant l'utilisation et la souscription aux événements de Castor. Ici, nous avons trois dimensions, mais dans la réalité, nous utiliserons plutôt des vecteurs avec des milliers de dimensions, afin d'être capable de capturer une sémantique la plus précise possible pour chaque document.

Si vous n'avez jamais fait de RAG, vous vous demandez sûrement comment obtenir un vecteur à partir d'un simple texte ? La réponse est plutôt simple et presque décevante : on va demander à une IA ! Il existe des modèles spécialement entraînés pour capturer la sémantique d'un texte et en extraire le vecteur correspondant. En anglais, cette représentation d'une valeur (textuelle, image ou autre) dans un format adapté (ici un vecteur) à un traitement par un algorithme s'appelle "embedding".

Une fois nos vecteurs calculés et stockés pour chaque document, nous pouvons nous occuper des entrées de l'utilisateur. Chaque fois qu'il interagit avec notre RAG, nous allons appliquer la même logique de vectorisation à son message. Avec ce nouveau vecteur, nous serons capables de faire une recherche vectorielle parmis tous nos documents afin de déterminer ceux les plus proches de la question de l'utilisateur.

La génération ✍️

Une fois que nous avons identifié les documents les plus pertinents, nous demanderons à notre LLM préféré de formuler une réponse pour l'utilisateur. Mais cette fois, nous allons lui fournir nous-mêmes les documents/connaissances sur lesquels il doit s'appuyer.

Cerise sur le gâteau, nous pouvons même lui demander :

de s'appuyer uniquement sur ces contenus fournis en ignorant son éventuelle connaissance interne ;
d'ajouter dans la réponse le lien correspondant au contenu, permettant à l'utilisateur de vérifier les sources.

Mais assez de théorie pour l'instant. Il est temps de passer à la pratique et de voir comment construire concrètement l'exemple que nous venons d'évoquer.

Mise en pratique

Nous allons chercher à créer un chatbot qui sera capable de répondre à n'importe quelle question à propos d'un site web qu'il aura auparavant ingéré. Pour ce faire, nous allons créer une application Symfony dans un projet dockerisé. Pour gagner du temps, nous nous baserons sur un template docker-starter pour nous consacrer sur l'essentiel.

Tout le code de cette démo se trouve dans un repository open source, n'hésitez pas à y jeter un œil pour approfondir cet article.

La base de données vectorielle 🐘

Pour stocker nos documents texte et leurs représentations vectorielles, tout en permettant une recherche vectorielle efficace, nous allons utiliser... PostgreSQL ! Plus précisément, PostgreSQL associé à l'extension pgvector, qui ajoute les fonctionnalités nécessaires pour effectuer des recherches basées sur la similarité vectorielle. Dans notre docker-compose.yml, on peut utiliser directement l'image pgvector/pgvector qui ajoute uniquement l'extension pgvector à l'image officielle de PostgreSQL :

# …
services:
    # …

    postgres:
        image: pgvector/pgvector:pg16
        # …

Découpage des pages en documents ✂️

Dans cette démo, j'ai choisi de crawler le site de la documentation au lieu de récupérer directement les documents markdown car je souhaitais créer un chatbot capable d'ingérer n'importe quel site, et pas uniquement une documentation markdown en particulier.

Plutôt que de créer un seul document pour chaque page, j'ai décidé que chaque page serait séparée en plusieurs sections. L'idée est d'avoir des documents plus granulaires pour aiguiller au mieux notre IA plutôt qu'un contenu conséquent qui risquerait de la perturber. Chaque fois qu'un titre sera détecté dans la page, une nouvelle section sera stockée en base de données. Dans l'idéal, chaque titre aura un id servant d'ancre afin que les URLs des sources soient plus précises pour l'utilisateur (c'est le souvent le cas avec les documentations générées depuis du markdown ou équivalent).

Imaginons la structure d'une page à l'URL /foobar :

<h1 id="lorem">Lorem</h1>
      <p>Ipsum dolor sit amet</p>

      <h2 id="consectetur">Consectetur</h2>
          <p>Adipiscing elit</p>

          <h3 id="sed">Sed</h3>
            <p>Do eiusmod tempor</p>

          <h3 id="incididunt">Incididunt</h3>
            <p>Ut labore et</p>

      <h2 id="dolore">Dolore</h2>
          <p>Magna aliqua</p>

Cela nous donnera les cinq documents suivants :

url: /foobar#lorem
title: Lorem
content: Ipsum dolor sit amet

—

url: /foobar#consectetur
title: Consectetur
content: Adipiscing elit

—

url: /foobar#sed
title: Sed
content: Do eiusmod tempor

—

url: /foobar#incididunt
title: Incididunt
content: Ut labore et

—

url: /foobar#dolore
title: Dolore
content: Magna aliqua

Voici un exemple simple de parsing du HTML et de découpage du contenu en fonction des titres à l'aide du DomCrawler de Symfony :

use Symfony\Component\DomCrawler\Crawler as DomCrawler;

class DocumentExtractor
{
    /** @return Document[] */
    public function extract(string $url, string $html): array
    {
        $crawler = new DomCrawler($html);
        $crawler = $crawler->filter('h1, h2, h3, h4, h5, h6');

        // Iterate over the h1-h6 titles
        foreach ($crawler as $node) {
            $documentUrl = $url;

            // Attach an anchor to the URL if title has an id
            if ($node instanceof \DOMElement && $node->hasAttribute('id')) {
                $documentUrl .= '#' . $node->getAttribute('id');
            }

            $title = $this->cleanContent($node->textContent);
            $content = '';
            $contentNode = $node->nextSibling;

            // Parse the content until the next title
            while ($contentNode && !$this->isTitle($contentNode)) {
                $content .= $contentNode->ownerDocument->saveHTML($contentNode);
                $contentNode = $contentNode->nextSibling;
            }

            $documents[] = new Document(
                $documentUrl,
                $title,
                $this->cleanContent($content),
            );
        }

        return $documents;
    }

    // …
}

Crawl du site 🕸️

Pour crawler le site, nous utiliserons le package spatie/crawler, qui, grâce à son utilisation du design pattern Observer, nous permet de nous brancher facilement dans le crawl et analyser chaque page, une par une :

use Spatie\Crawler\Crawler as SpatieCrawler;
use Spatie\Crawler\CrawlProfiles\CrawlInternalUrls;

class Crawler
{
    public function __construct(private readonly Observer $observer) {}

    /** @return Document[]  */
    public function crawl(string $url): array
    {
        $this->observer->reset();

        SpatieCrawler::create()
            ->setCrawlObserver($this->observer)
            ->setCrawlProfile(new CrawlInternalUrls($url))
            ->acceptNofollowLinks()
            ->setMaximumDepth(1000)
            ->startCrawling($url)
        ;

        return $this->observer->getDocuments();
    }
}

Et voici la définition de notre Observer, qui sera chargée d'appeler le DocumentExtractor définit plus tôt :

use GuzzleHttp\Exception\RequestException;
use Psr\Http\Message\ResponseInterface;
use Psr\Http\Message\UriInterface;
use Psr\Log\LoggerInterface;
use Spatie\Crawler\CrawlObservers\CrawlObserver;
use Symfony\Contracts\Service\ResetInterface;

class Observer extends CrawlObserver implements ResetInterface
{
    /** @var Document[] */
    public array $documents = [];

    public function __construct(
        private readonly DocumentExtractor $extractor,
        private readonly LoggerInterface $logger,
    ) {
    }

    public function reset()
    {
        $this->documents = [];
    }

    public function crawled(
        UriInterface $url,
        ResponseInterface $response,
        ?UriInterface $foundOnUrl = null,
        ?string $linkText = null,
    ): void {
        $html = (string) $response->getBody();

        if (!$html) {
            return;
        }

        $stringUrl = (string) $url;
        $this->documents = array_merge($this->documents, $this->extractor->extract($stringUrl, $html));
    }

    public function crawlFailed(
        UriInterface $url,
        RequestException $requestException,
        ?UriInterface $foundOnUrl = null,
        ?string $linkText = null,
    ): void {
        $this->logger->error('Could not crawl this url.', [
            'url' => (string) $url,
            'exception' => $requestException->getMessage(),
        ]);
    }

    public function finishedCrawling(): void {}
}

Maintenant que l'on a récupéré tous nos documents, nous pouvons passer à l'étape d'après : calculer leur représentation vectorielle.

Vectorisation des documents ➗

C'est ici que nous commençons à mettre les mains dans le camboui. Comment faire pour obtenir les "embeddings", c'est-à -dire, les vecteurs correspondant à nos documents ? Il faut savoir que la plupart des services / modèles d'IA générative proposent directement des outils pour calculer nos embeddings.

OpenAI ne fait pas exception et propose une API dédiée. Rien de bien sorcier finalement, on se contentera d'appeler ce endpoint en lui passant le texte à vectoriser :

class OpenAIClient
{
    public function __construct(
        #[Autowire('%env(OPENAI_API_KEY)%')]
        private readonly string $apiKey,
        private readonly HttpClientInterface $client,
    ) {
    }

    /** @return array<float> */
    public function getEmbeddings(string $content): array
    {
        $data = $this->call('/v1/embeddings', [
            'model' => 'text-embedding-3-small', // "small" model will produce vectors of 1536 dimensions
            'input' => $content,
        ]);

        if (!($data['data'][0]['embedding'] ?? false)) {
            throw new \RuntimeException('Could not get embeddings from OpenAI response.');
        }

        return $data['data'][0]['embedding'];
    }

    private function call(string $endpoint, array $data): array
    {
        $response = $this->client->request('POST', "https://api.openai.com{$endpoint}", [
            'headers' => [
                'Authorization' => "Bearer {$this->apiKey}",
            ],
            'json' => $data,
        ]);

        return $response->toArray();
    }
}

Pour chaque document, on appellera cet endpoint en passant le contenu du document à vectoriser. On récupère ainsi, pour chacun, un vecteur qui n'est finalement qu'un tableau de float. En utilisant le modèle text-embedding-3-small d'OpenAI, la taille du vecteur sera de 1536 dimensions. Il est tout à fait possible de changer de modèle. Cependant, plus un modèle retourne de gros vecteurs, plus il sera précis, mais plus il coûtera cher côté OpenAI et plus il demandera de place à stocker dans notre base de données.

Si vous regardez le code de la démo, vous verrez que j'ai ajouté une couche de cache sur tous les appels à OpenAI. Comme l'API n'est pas gratuite, cela permet d'éviter de consommer des crédits quand les contenus à vectoriser ne changent pas entre les crawls.

Stockage des documents et leurs vecteurs 💾

J'ai choisi d'utiliser le package partITech/doctrine-pgvector qui intègre dans Doctrine tout ce dont on a besoin pour tirer parti de l'extension pgvector.

Pour stocker nos vecteurs, nous aurons besoin d'utiliser le type vector. Il faut donc l'ajouter dans la configuration DBAL de Doctrine pour pouvoir l'utiliser dans notre entité :

# config/packages/doctrine.yaml

doctrine:
    dbal:
        # …

        types:
            vector: Partitech\DoctrinePgVector\Type\VectorType

Nous pouvons maintenant définir notre document avec tous les champs nécessaires. Pour le champ embeddings, il faudra spécifier la taille attendue de notre vecteur, soit dans notre cas 1536 :

#[ORM\Entity()]
class Document
{
    public const VECTOR_LENGTH = 1536;

    #[ORM\Id]
    #[ORM\GeneratedValue(strategy: 'NONE')]
    #[ORM\Column(type: 'guid', nullable: false)]
    public readonly string $id;

    /** @var float[] */
    #[ORM\Column(type: 'vector', length: self::VECTOR_LENGTH)]
    public array $embeddings;

    public function __construct(
        #[ORM\Column(type: 'text')]
        public readonly string $url,

        #[ORM\Column(type: 'text')]
        public readonly string $title,

        #[ORM\Column(type: 'text')]
        public readonly string $content,
    ) {
        $this->id = \uuid_create();
    }
}

Voilà à quoi ressemble nos documents et leurs vecteurs dans notre base de données :

Nos documents étant maintenant stockés en base, nous pouvons nous attaquer à la recherche de proximité sémantique de nos documents avec un message saisi par l'utilisateur.

Recherche vectorielle 🔎

Vous vous souvenez du schéma en début d'article illustrant trois vecteurs dans un espace à trois dimensions ? C'est maintenant que nous allons mesurer à quel point ces vecteurs sont similaires entre eux. Heureusement, pas besoin de réinventer la roue pour y parvenir : les mathématiques nous fournissent déjà les outils nécessaires. Dans ce cas, nous utiliserons la similarité cosinus, qui calcule le cosinus de l'angle entre deux vecteurs. Inutile de plonger trop profondément dans les détails mathématiques : l'extension pgvector nous offre directement une fonction pratique pour cela, 'cosine_similarity'.

L'extension Doctrine pgvector supporte cette fonction, nous n'aurons qu'à l'enregistrer dans la configuration de Doctrine :

# config/packages/doctrine.yaml

doctrine:
    orm:
        # …

        dql:
            string_functions:
                cosine_similarity: Partitech\DoctrinePgVector\Query\CosineSimilarity

Nous utiliserons la fonction cosine_similarity() dans la section ORDER BY, qui nous permettra de trier les documents par ordre de similarité par rapport à la représentation vectorielle du message de l'utilisateur. Il suffira de passer le message vectorisé (le tableau de nombre flottants $embeddings) de l'utilisateur à la méthode findNearest() du DocumentRepository que nous allons créer :

use App\Entity\Document;
use Doctrine\Bundle\DoctrineBundle\Repository\ServiceEntityRepository;
use Doctrine\Persistence\ManagerRegistry;

/** @extends ServiceEntityRepository<Document> */
class DocumentRepository extends ServiceEntityRepository
{
    // …

    /**
     * @param float[] $embeddings
     *
     * @return Document[]
     */
    public function findNearest(array $embeddings): array
    {
        return $this->createQueryBuilder('s')
            ->orderBy('cosine_similarity(s.embeddings, :embeddings)', 'DESC')
            ->setParameter('embeddings', $embeddings, 'vector')
            ->setMaxResults(5)
            ->getQuery()
            ->getResult()
        ;
    }
}

Une fois que l'on a trouvé les cinq documents les plus similaires à ce qu'a demandé notre utilisateur, il ne nous reste qu'à demander à notre AI de générer une réponse en s'appuyant sur ces documents en question.

Génération de la réponse à l'utilisateur 💬

La plupart des modèles d'IA générative fournissent une API permettant de configurer le prompt qui sera envoyé à l'IA pour lui expliquer ce que l'on attend d'elle. Le format attendu de la réponse, le ton à employer mais surtout les informations sur lesquelles s'appuyer pour répondre à l'utilisateur.

Plus tôt, nous avons utilisé OpenAI pour le calcul des embeddings. Par simplicité, c'est donc avec ce service que nous continuerons pour la partie génération de la réponse. Ici nous utiliserons l'endpoint /v1/chat/completions. On enverra à cet endpoint 2 choses :

le modèle à employer (on utilisera simplement gpt-4o qui est disponible à l'heure où j'écris cet article) ;
les "messages" qui permettront au modèle de comprendre la situation et d'y répondre.

OpenAI supporte plusieurs type de "messages" :

les messages system, qui permettent d'envoyer des prompt et de donner tout type d'indications notre modèle pour l'aiguiller dans sa génération ;
les messages user qui contiendront, comme leur nom l'indique, les messages saisi par l'utilisateur ;
les messages assistant qui contiendront les réponses précédentes générées par notre assistant, ce qui donnera une espèce d'historique / de mémoire à l'assistant afin d'offrir une conversation plus naturelle (pas besoin de tout re-préciser à chaque message, l'assistant se souviendra du contexte) ;
les messages tool qui fourniront des fonctions / outils que l'IA pourra appeler pour récupérer plus d'informations si nécessaire, faire des requêtes à une API, etc. (nous n'en aurons toutefois pas besoin dans le cadre de cet article).

Afin de conserver l'historique et être capable de la redonner au LLM, nous stockerons tous les messages (utilisateurs et réponses de l'IA) dans une entité Message. Ainsi, chaque fois que nous demanderons à notre IA une réponse, en plus des documents pertinents, nous lui enverrons l'historique de la conversation ($historyMessages dans l'exemple suivant).

class OpenAIClient
{
    // …

    /**
     * @param Document[] $documents
     */
    public function getAnswer(array $documents, array $historyMessages): string
    {
        // Send prompt to the IA in a `system` message

        $prompt = "Notre prompt. Définit plus bas dans l'article";

        $messages = [
            [
                'role' => 'system',
                'content' => $prompt,
            ],
        ];

        // Send most similar documents in a new `system` message

        $relevantInformation = 'Relevant information: \n';
        foreach ($documents as $document) {
            $relevantInformation .= json_encode([
                    'title' => $document->title,
                    'content' => $document->content,
                    'url' => $document->url,
                ]) . "\n";
        }

        $messages[] = [
            'role' => 'system',
            'content' => $relevantInformation,
        ];

        // Send conversation history to give IA some context about previous messages

        foreach ($historyMessages as $message) {
            $messages[] = [
                'role' => $message->isMe ? 'user' : 'assistant',
                'content' => $message->content,
            ];
        }

        $data = $this->call('/v1/chat/completions', [
            'model' => 'gpt-4o',
            'messages' => $messages,
        ]);

        if (!($data['choices'][0]['message']['content'] ?? false)) {
            throw new \RuntimeException('Could not get completion from OpenAI response.');
        }

        return $data['choices'][0]['message']['content'];
    }

Concentrons-nous sur notre prompt, car c'est finalement lui qui va définir le cœur même de notre application. Pour tirer pleinement parti de notre RAG, nous allons pouvoir demander à l'IA de s'appuyer sur les informations/documents que nous aurons trouvés par nous-mêmes, ainsi que de répondre de manière concise, en utilisant les exemples présents dans notre documentation. Autre valeur ajoutée, nous allons pouvoir lui demander de sourcer ses réponses, afin que l'utilisateur puisse vérifier les dires de notre assistant. Voici un exemple de prompt utilisé dans notre POC :

You are a friendly chatbot.
You respond in a concise, technically credible tone (but do not hesitate to add examples if needed).
You only use information from the provided information.
Please add the link of the relevant documents to the end of your response (do not invent url, only use the one we provided).

OpenAI nous renverra ainsi la réponse à donner à l'utilisateur. Le message généré par OpenAI utilise le format markdown, ce qui nous permettra par la suite de le mettre en forme dans notre application :

exemples de code avec les balises code et pre et la coloration syntaxique qui va bien pour chaque langage ;
liens ;
sémantiques avec les balises em, b, etc.

Le prompt ci-dessus est très certainement perfectible. La création de prompts adaptés est d'ailleurs une compétence à part entière, que l'on retrouvera souvent sous le terme de "prompt engineering". Mais nous n'irons pas plus loin ici, car là n'est pas le but de cet article. En revanche, il est désormais temps de brancher ensemble les différentes sections que nous avons vu afin de créer notre POC.

Le POC 🛠️

La partie crawl, découpages des pages en documents, vectorisation de chacun d'entre eux et stockage en base de données se fera dans une commande Symfony classique :

use App\Crawl\Crawler;
use App\Entity\Document;
use App\OpenAI\Client;
use Doctrine\ORM\EntityManagerInterface;
use Symfony\Component\Console\Attribute\AsCommand;
use Symfony\Component\Console\Command\Command;
use Symfony\Component\Console\Input\InputInterface;
use Symfony\Component\Console\Output\OutputInterface;
use Symfony\Component\Console\Style\SymfonyStyle;
use Symfony\Component\DependencyInjection\Attribute\Autowire;

#[AsCommand(name: 'app:crawl', description: 'Crawl the website to extract content')]
class CrawlCommand extends Command
{
    public function __construct(
        private readonly Crawler $crawler,
        private readonly Client $client,
        private readonly EntityManagerInterface $entityManager,
        #[Autowire('%env(DOCUMENTATION_URL)%')]
        private readonly string $documentationUrl,
    ) {
        parent::__construct();
    }

    protected function execute(InputInterface $input, OutputInterface $output): int
    {
        $io = new SymfonyStyle($input, $output);
        $url = $this->documentationUrl;

        if (false === filter_var($url, \FILTER_VALIDATE_URL)) {
            $io->error('Invalid url.');

            return Command::FAILURE;
        }

        $io->info('Crawling the website.');

        $documents = $this->crawler->crawl($url);

        $io->note(sprintf('Found %d documents.', \count($documents)));

        $io->info('Extracting embeddings.');

        foreach ($documents as $document) {
            $embeddings = $this->client->getEmbeddings($document->content);

            $document->setEmbeddings($embeddings);
        }

        $io->info('Persisting data.');

        foreach ($documents as $document) {
            $this->entityManager->persist($document);
        }

        $this->entityManager->flush();

        $io->success('Finished crawling this website.');

        return Command::SUCCESS;
    }
}

Il faudra lancer cette commande une première fois, avant toute interaction avec le front, pour avoir les documents disponibles en base de données.

En parlant du front, c'est justement le moment de s'en occuper. Et on va se faire plaisir et utiliser les dernières fonctionnalités de Symfony :

AssetMapper et ImportMap pour construire la stack front sans besoin de configurer node ni webpack
Symfony UX et un Twig component pour avoir un minimum d'interactivité sans avoir besoin d'écrire de JS.

On ajoutera également le package league/commonmark pour la conversion markdown vers html des messages de l'IA et nous en ferons une extension Twig pour l'utiliser facilement dans notre component :

use League\CommonMark\MarkdownConverter;
use Twig\Extension\AbstractExtension;
use Twig\TwigFilter;

class MarkdownExtension extends AbstractExtension
{
    public function __construct(
        private readonly MarkdownConverter $markdownConverter,
    ) {
    }

    public function getFilters(): array
    {
        return [
            new TwigFilter('markdown', $this->markdownConverter->convert(...), ['is_safe' => ['html']]),
        ];
    }
}

On branche ensuite toute la partie formulaire, affichage de la conversation, recherche des documents et génération de la réponse utilisateur dans un twig component. Voici ce qu'il se passe dans le traitement du formulaire du chat :

// On récupère le message de l'utilisateur
$this->submitForm();
$userPrompt = $this->getForm()->get('userPrompt')->getData();

// On le stocke dans l'historique de la conversation

$message = new Message($userPrompt, true);
$this->entityManager->persist($message);
$this->entityManager->flush();

// On vectorise ce message

$embeddings = $this->client->getEmbeddings($userPrompt);

// Puis on cherche les documents les plus proches sémantiquement

$documents = $this->documentRepository->findNearest($embeddings);

// On demande à l'IA de générer notre réponse en fonction de la conversation

$messages = $this->messageRepository->findLatest();
$answer = $this->client->getAnswer($documents, $messages);

// On stocke la réponses dans la conversation

$message = new Message($answer, false);
$this->entityManager->persist($message);
$this->entityManager->flush();

$this->resetForm();

// On peut maintenant afficher la conversation
// …

Avec bootstrap et un peu de CSS custom, on arrive à un POC qui ressemble à ça ✨ (oui, vous l'aurez deviné, je ne suis pas développeur frontend) :

Et voilà qui conclut cet article et notre démo. Le POC fonctionne même s'il pourrait être amélioré sur de très nombreux points : gestion d'utilisateurs et conversation propre à chacun, micro interactions dans le navigateur, possibilité de laisser à l'utilisateur d'analyser le site de son choix, etc 🤓.

Conclusion

À travers cet article, nous avons vu ce qu'il se cachait derrière le concept de RAG et comment cela fonctionnait. Nous avons pu découvrir les différentes notions que ceux-ci impliquent, comme les espaces vectoriels, les embeddings ou encore la similarité cosinus.

Mais surtout, nous avons pu voir comment nous pouvions créer un RAG nous-mêmes, sous la forme d'un chatbot permettant de répondre à des questions sur un corpus documentaire bien à nous. Je rappelle que le code source du POC est disponible publiquement si jamais vous vouliez le tester par vous-même ou explorer plus en profondeur son fonctionnement.

Dans cette démonstration, nous n'avons utilisé que les outils fournis par OpenAI. L'objectif était surtout de simplifier l'article en utilisant un service "clé en main" qui ne demande quasi rien d'autre que d'appeler une API pour obtenir les données dont nous avions besoin. Cependant, bien que cette société ait aidé à la démocratisation de l'IA auprès du grand public, notamment avec son outil ChatGPT, elle est loin d'être irréprochable. On peut d'ailleurs s'interroger sur les dangers de lui fournir tout le contenu de nos documents, potentiellement privés si l'on travaille sur une documentation interne par exemple.

Le domaine de l'IA a connu un essor considérable ces dernières années, et il est désormais plus simple que jamais de faire tourner nos propres modèles en local pour éviter toute fuite de données, comme par exemple Ollama. N'hésitez pas à laisser un commentaire si vous seriez intéressé par un prochain article qui utiliserait un modèle local à la place de ceux d'OpenAI.

Sources

Quelques sources supplémentaires utilisées pour mes recherches et la rédaction de cet article et son POC :

Du travail solitaire à l’engagement collectif : la dynamique de la veille

2024-10-22T15:15:00+02:00

Quand Cyril et Audrey de l’École O’Clock m’ont proposé d’animer un meetup autour de la veille technologique, je me suis souvenu d’une phrase du podcast IFTTD :

Le problème avec un ingénieur, c’est que lorsqu’on lui montre un ciel bleu, ce qu’il voit, c’est la diffraction de la lumière.

Même sans être développeur moi-même, je connais cette obsession pour les détails techniques que peuvent avoir mes équipes. C’est précisément cette passion pour la technicité que la veille technologique permet de canaliser, tout en gardant une vision globale.

Une autre chose que j’ai retenu récemment, c’est l’interview de Maya Noel, dirigeante de France Digitale, qui en parle si bien. Elle a mis l’accent sur un point essentiel : la maîtrise technique, c’est bien, mais ça ne suffit plus.

Il faut constamment évoluer. Les technologies bougent, et ce qui compte vraiment, c’est l’apprentissage continu et l’adaptation. Peu importe le niveau d’expérience, ce qui fait la différence, c’est la curiosité et la capacité à comprendre le contexte. Ça semble un peu bateau comme ça, non ? Mais avoir un avis sur les technologies qu’on manipule est essentiel, même si on a pas tous 10 ans d’expérience. Maya, qui vient du monde du recrutement, compare une équipe de développeurs à une équipe de football : il est impossible d’avoir uniquement des attaquants. Les meilleures entreprises recherchent des profils équilibrés, des développeurs capables d’apprendre et de s’adapter sur le long terme. Savoir coder, c’est la base, mais comprendre pourquoi vous codez, pour qui vous le faites, et comment cela s’intègre dans un projet global (et avoir une appétence business), c’est ce qui permet de se démarquer.

Un autre exemple que j’ai partagé durant ce talk est une conférence que j’ai vue récemment au Forum PHP, présentée par Pascal Martin : L’aventure d’une requête HTTP. Il aime poser cette question en entretien : "Que se passe-t-il quand vous tapez une URL dans votre navigateur ?" Ce n’est pas un piège, mais une ouverture vers la complexité du web moderne. Derrière chaque requête HTTP, il existe des couches entières de technologie. C’est là que l’approche T-shape des compétences prend tout son sens : une base solide en connaissances larges est nécessaire, mais c’est la profondeur dans certains domaines qui permet de se distinguer. Pour développer cette profondeur, il faut être en veille constante. Comme Pascal l’a si bien dit :

Ce métier, c’est un assemblage de multiples compétences.

La veille technologique : un impératif ? 🤷

La veille ne se résume pas à scroller ou écouter des podcasts, c’est un travail de fond qui nécessite également de s’intéresser au marché. Il y a pour cela par exemple le baromètre annuel de l’AFUP, et bien sûr, l’enquête de StackOverflow. Cette enquête (Dimension international même si elle reflète plutôt un panel américain avec ±19% de répondant basés aux État-Unis), à laquelle plus de 65 000 développeurs participent chaque année, offre une vision globale sur les technologies et outils qu’ils utilisent, ceux qu’ils souhaitent apprendre, et même leur point de vue sur l’IA et l’expérience développeur.

Il est également essentiel d’amener un peu d’humain dans sa veille. Depuis que je suis à JoliCode, on m’a toujours incité à participer à des conférences comme Paris Web, DotJS, ou le Forum PHP. Pour ceux qui préfèrent un cadre plus intimiste, il existe de nombreux meetups locaux à Paris ou ailleurs. Ne sous-estimez pas l’impact d’une simple participation, car il y a des événements (et des rencontres) qui peuvent être une véritable source de motivation et ouvrir de nouvelles perspectives.

Internet : une effervescence quotidienne 🌊

Pour illustrer à quel point la veille est indispensable, prenons l’exemple de GitHub, un acteur clé dans l’univers des développeurs. Chaque année, 413 millions de contributions open source sont effectuées. Du côté de YouTube, c'est une avalanche de contenu avec 720 000 heures de vidéos publiées chaque jour. Sur X, les stats aussi explosent tout !

Ces chiffres illustrent en partie la rapidité avec laquelle le monde de la tech évolue. Avec un volume pareil, il est impossible de tout découvrir, tout lire, ou tout expérimenter. D’où l’importance de bien choisir ses sources et d’être stratégique dans sa veille.

Personnellement, j’utilise Daily.dev pour me créer un feed sur mesure. C’est un réseau qui permet de collaborer et d’apprendre dans un environnement privé, loin du bruit d’autres plateformes. Les “squads” sont particulièrement intéressantes : elles permettent de suivre des groupes d’intérêt, souvent sur invitation, garantissant un haut niveau de contenu. Ça m’a permis aussi de découvrir les sources partagées, et in finé de supers nouveaux sites à suivre.

GitHub Trending est aussi une excellente ressource pour découvrir les projets les plus “hype” du moment. Cela permet de voir comment sont organisés, documentés et codés les projets qui attirent le plus d’attention.

Podcast, Substack et lectures 🧠

La veille ne se limite pas à des sites web. J’ai également parlé de podcasts qui m’ont réconcilié avec le format : CTO’Z, IFTTD, Génération Remote, et Code Garage. Ils sont devenus des incontournables pour moi et on s’y attache rapidement. Côté lecture, il existe aussi des newsletters Substack de qualité, comme HappyToDev, qui traite de PHP, Laravel et Vue.js, ou encore Hybrid Hacker, avec un focus plus humain sur le développement.

En ce qui concerne les livres, j’ai mentionné "La Dette Technique" écrit par Bastien Jaillot, qui met enfin des mots sur ce concept souvent flou et "Engineering management for the rest of us” de Sarah Drasner et qu’il faut que je rende à Damien ! Je suis sûr que vous en avez mille fois plus que moi en tête !

Une initiative collective : digest.club

À cet égard, l’initiative digest.club, développée par Premier Octet, méritait d’être soulignée. Ce projet open-source permet de partager notre veille, et vise aussi à lutter contre la diminution de la motivation, quand la veille devient un effort conscient. digest.club invite donc chacun à contribuer, à partager et à s’engager collectivement dans ce parcours d’apprentissage. Si l’outil vous intéresse, on parle de notre usage de cet outil sur notre blog.

Contribuer pour mieux apprendre ✍️

Faire de la veille, c’est aussi contribuer. Avec Hacktoberfest, c’est l’occasion idéale pour plonger dans l’open source. Grâce au label “Good First Issue”, il est aussi possible de trouver des tickets adaptés aux débutants. Si cette démarche n’a jamais été franchie, c’est le moment ou jamais !

La clé pour réussir en tant que développeur en 2024 semble résider dans l’apprentissage continu, la curiosité et l’empathie. Que l’on soit novice ou expérimenté, se tenir informé, participer à des événements et contribuer à des projets open-source enrichit non seulement les compétences techniques, mais renforce aussi le lien humain au sein de notre communauté.

Après tout, c’est cette connexion qui transforme le développement en une aventure collective, où chaque contribution compte et chaque voix a son importance.

Bonne veille !

Ce que nous avons retenu du Forum PHP 2024, jour 2

2024-10-17T15:00:00+02:00

Comme chaque année l’équipe de JoliCode était présente au Forum PHP de l’AFUP, le plus gros événement PHP de l’Hexagone, pour deux jours de conférence sur l’éco-système !

Cet article est la suite du premier jour, nous allons vous partager nos take-aways, ce que nous y avons découvert, et ce que nous en retenons.

Il y a encore ici beaucoup de belles choses à raconter, à vos lunettes !

L’aventure d’une requête HTTP — ou le chemin de la vie des devs

Pascal Martin est principal engineer chez Bedrock et conférencier depuis… 2004 ! Sa conférence, intitulée "L’aventure d’une requête HTTP", a exploré un sujet que tout le monde utilise quotidiennement, mais qui reste souvent mystérieux : que se passe-t-il lorsqu’on saisit une URL dans la barre d’adresse de son navigateur ?

Cette question, que Pascal aime poser en entretien (nous aussi 🤗), n’est pas un piège, mais un tremplin pour aborder la complexité d’une requête HTTP et les nombreuses technologies qu’elle met en jeu.

Durant la conférence, il a mentionné des outils comme Wireshark ou Sysdig, essentiels pour observer et comprendre le chemin d’une requête. Un des points forts de son intervention était de souligner l’importance de l’observabilité pour les développeurs. Comprendre ce qui se passe en coulisse est crucial pour optimiser des projets et améliorer ses compétences.

Comme il l’a si bien rappelé : "notre métier est un assemblage de multiples compétences". Les conférences comme celles-ci permettent de choisir les technologies à expérimenter et ouvrent des perspectives de carrière insoupçonnées !

Sketch de la conférence par Mathieu Desnouveaux.

Créer des interfaces d’administration rapidement avec Symfony UX et Sylius

Loïc Frémont fait partie de la core team de Sylius et nous a parlé d'un sujet qui résonne fort avec notre article récent : Administrer une entité custom dans un back-office Sylius.

Il a débuté sa présentation par la Grid Standalone de Sylius, un composant maintenant totalement découplé du système de ressources. Il permet de construire des interfaces d’administration performantes sans avoir à gérer toute la logique liée aux ressources, ce qui offre plus de flexibilité pour intégrer cette solution dans des projets non-e-commerce.

En revenant sur l'évolution historique, il a rappelé que l'intégration de Semantic UI en 2016, suivie de AdminLTE et de Bootstrap, était devenue vieillissante. Ces solutions n'étaient plus adaptées aux besoins actuels, notamment en termes d'extensibilité et d'expérience développeur (DX). C’est pourquoi en 2019, Sylius a introduit un mécanisme de templates d’événements, conçu pour remplacer les traditionnels blocs Sonata et apporter plus de souplesse. Aujourd'hui, ces "event templates" ont été remplacés par des hooks Twig, facilitant encore davantage la personnalisation des interfaces administratives.

Il a aussi parlé de Monofony, un projet basé sur Symfony et utilisant les composants de Sylius. Ce projet permet d'utiliser les fonctionnalités clés de Sylius, comme la Grid et le système de ressources, sans la partie e-commerce. Il est cependant difficile de l’installer sur un projet existant car il dépend de certains packages du monorepos de Sylius.

Il nous a ensuite montré les différentes étapes pour construire rapidement une admin fonctionnelle en prenant l’exemple d’une gestion de conférenciers :

Créer l’entité Speaker avec la commande make:entity ;
Créer le formType avec la commande make:form ;
Créer la grid toujours avec le MakerBundle make:grid ;
Déclarer l’entité en tant que Resource Sylius grace à l’attribute #[AsResource] ;
Modifier la grid afin de personnaliser les filtres, les champs qu’on affiche ainsi que les actions possibles (notamment une action qui permet aussi de filtrer la liste affichée).

Le rôle de Symfony UX a très peu été abordé par Loïc, il y a cependant le composant ux_autocomplete. Ce dernier permet d’ajouter des champs d’autocomplétion pour les filtres, rendant l’interface d’administration plus fluide et agréable à utiliser pour les utilisateurs finaux.

Pour conclure, il a indiqué que la documentation n’était pas encore écrite mais que le code était déjà prêt à être utilisé.

Utiliser une faille glibc pour attaquer le moteur PHP

Charles FOL est chercheur en sécurité, et il nous a raconté comment il y a quelques mois, il a découvert un bug vieux de 24 ans dans glibc, la librairie de base des programmes linux.

Le bug est très compliqué à atteindre, sauf depuis PHP, qui permet son exploitation depuis le web.

Via ce bug, et beaucoup de ténacité, Charles peut convertir n'importe quelle lecture de fichier en RCE : Remote Code Execution (donc prendre le contrôle de votre serveur).

Exemple de code qui pourrait être exploité pour prendre le contrôle :

echo file_get_contents($_GET['file']);

Oui ce code n'est pas très malin, mais la faille est exploitable de bien d'autres manières car elle exploite en réalité iconv. Tout ce qui touche à iconv est donc impacté. Saviez-vous que symfony/polyfill-mbstring est basé sur iconv ? 😬

Essayons de résumer le cheminement :

PHP a un système de filtre à la lecture de fichier : php://filter/ ;
Il y a un filtre de conversion, utilisant iconv : php://filter/convert.iconv.UTF-8.UTF-16/resource=/etc/passwd ; ici on traduit le fichier /etc/passwd de UTF-8 vers UTF-16 ;
À la base le chercheur était en train de jouer avec ces filtres pour modifier le contenu du fichier, en effet, à force d'enchaîner des centaines de conversions, le contenu textuel du fichier peut être forcé ! Par exemple, rendre un fichier /etc/passwd valide en JSON pour le voler 🙈
Une librairie a été créée pour générer ces filtres.

Ça aurait pu s'arrêter là, c'est déjà chouette et très impressionnant ! 😋

Mais à force de jouer avec les conversions de charset, l'auteur est tombé sur un cas exceptionnel qui fait crasher le système. Quand on convertit en ISO-2022-CN-EXT, iconv a de fortes chances de rater son allocation mémoire et de faire un Out-of-bound write (écrire dans un espace qui n'est pas le sien).

Vous pouvez voir un POC PHP complet ici, segfault garantie.

$input = "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA"
."AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA" .
"AAA劄劄\n劄劄\n劄劄\n劄\n劄\n劄\n劄";
$output = iconv("UTF-8", "ISO-2022-CN-EXT", $input);

Il est donc possible de manipuler la mémoire et donc on obtient le graal : une RCE, via le remplacement d'un pointeur de fonction !

Cette partie de l'exploit n'a pas été détaillée dans le talk, mais un script existe pour l'exploiter. Ce qu'il faut retenir, c'est qu'aujourd'hui, une faille de lecture de fichier se transforme très rapidement en RCE et c'est le carnage !

Si vous voulez voir comment la HEAP PHP est manipulée via ce bug, c'est sur le blog de Ambionics, qui détaille en trois parties toute l'histoire de la CVE-2024-2961.

Les objets paresseux en PHP

Nicolas Grekas aime beaucoup les objets paresseux 😄 et c'est en effet très pratique, que ça soit pour nos services "lazy" ou pour nos entités Doctrine non hydratées tant qu'on y accède pas. On gagne du temps, de la mémoire et donc de la performance.

Nous avons déjà parlé des différents types d'objets paresseux en PHP dans l'article de Baptiste, avec un cas d'usage sur les appels HTTP. Nous vous en recommandons la lecture.

La grosse nouveauté ici c'est le support natif dans PHP de cette fonctionnalité, prévue pour PHP 8.4 !

Ça va se passer dans ReflectionClass et ReflectionProperty, nous allons pouvoir déclarer des classes lazy et contrôler comment l'initialisation se fait ou ne se fait pas :

class MyClass
{
    public function __construct(private int $foo)
    {
        // Heavy initialization logic here.
    }
    // ...
}

$initializer = static function (MyClass $ghost): void {
    $ghost->__construct(123);
};

$reflector = new ReflectionClass(MyClass::class);
$object = $reflector->newLazyGhost($initializer);

// At this point, $object is a lazy ghost object.

Avec newLazyGhost, nous avons dit à PHP que MyClass ne doit plus être bootée comme d'habitude, son constructeur ne doit pas être exécuté à chaque création d'objet.

Nous pouvons aussi manipuler les données et déclarer certaines propriétés comme connues / accessible sans déclencher l'initialisation :

// ID is already known and can be accessed without triggering initialization
$this->reflector->getProperty('id')->setRawValueWithoutLazyInitialization($entity, $id);

Avec cet appel, nous avons mis une valeur dans "id", et précisé que lire cette propriété ne doit pas déclencher le constructeur ; comme avec Doctrine et une entité proxy par exemple.

L'arrivée de cette feature dans PHP va permettre de débloquer quelques cas d'usages, rendre lazy des services avec le mot clé "final" par exemple. Vivement PHP 8.4 !

Optimiser les performances de votre API avec AutoMapper

Salle comble pour la seconde intervention de Joël, qui nous a présenté l’AutoMapper, une bibliothèque open source made by JoliCode 💛

Si vous n’êtes pas encore familier avec cette bibliothèque, sachez qu’elle vise à éliminer le code boilerplate lié au mapping d’un schéma (object ou array) à un autre. Son utilisation est comparable à celle du Serializer de Symfony, mais elle génère du code au lieu de s’appuyer sur des métadonnées, améliorant sensiblement les performances. Elle est particulièrement adaptée dans un projet Symfony, conjointement à API Platform et nécessite un typage fort.

Joël met l’accent sur une migration endpoint par endpoint, il n’est pas question de tout migrer d’un coup. Voyons les étapes à suivre pour utiliser l’AutoMapper, de sa configuration à son utilisation avec les attributs et les transformers.

Configuration

Après avoir installé et enregistré le bundle dans le fichier config/bundles.php, il suffit d’ajouter quelques lignes de configuration et l’attribut #[Mapper(...)] aux entités voulues.

automapper:
    # ...
    mapping:
        paths:
          - "%kernel.project_dir%/src/Entity"

#[AutoMapper\Attribute\Mapper(target: 'array')]
class Project {
    //...

Utilisation

Par défaut, vous n’avez rien à faire. L’AutoMapper va essayer de mapper vos propriétés automagiquement 🧙. Cependant si vous avez des normalizers custom, il est nécessaire de les migrer vers des transformers puis de les configurer avec l’attribut adéquat.

#[MapTo(name: 'requestsEvolution', transformer: RequestEvolutionTransformer::class)]
class Project {
    //...

À noter, l’argument transformer supporte l’Expression Language de Symfony.

Il est également possible d’utiliser l’attribut inverse pour définir un mapping depuis un DTO.

class ProjectDto {
    #[MapFrom(
        source: Project::class,
        transformer: 'service("permissions_builder").buildProjectPermissions(source)',
    )]
    public array $permissions;

    // ...

D’ailleurs, Joël conseille d’user (et d’abuser) des DTO, 1 endpoint = 1 DTO, et pour deux grandes raisons :

Typage fort et propriétés auto documentées ;
Code plus lisible : plus besoin de groupes de sérialisation.

L’AutoMapper a maintenant sa section dans le Profiler de Symfony, bien pratique pour débugger un souci de mapping !

Pour aller plus loin, vous pouvez consulter les slides de la conférence, la documentation ou le dernier article de notre blog à ce sujet.

L'Orienté Objet au Cœur du Templating Symfony : Découvrez TwigComponent et LiveComponent

Felix Eymonot est venu nous présenter la dernière évolution en matière de templating sur Symfony, les Twig et Live Components.

L’idée est simple, découper les templates en composants qui chacun est lié à une classe PHP qui s’occupe de gérer leurs données.

Ces composants s’intègrent en respectant 4 principes clés :

Réutilisabilité ;
Encapsulation ;
Modularité ;
Interaction.

L’objectif final de Symfony UX avec ces composants est donc des template réutilisables et orientés objet, auxquels les développeurs backs n’auraient pas peur de toucher.

Pour créer des Components, on commence par définir un dossier dans lequel ils iront. On peut ensuite le remplir à la main, où à l’aide de la commande fournie par le MakerBundle qui génère la classe PHP + le template Twig. Une classe de Component peut avoir des propriétés privées, auxquelles elle seule peut accéder, et des propriétés publiques, qui seront accessibles directement depuis le template.

Il reste néanmoins possible de passer des données dans les templates sans faire appel à sa classe PHP grâce à la variable “attribute” qui apparaît dans chaque template de component. Elle peut être remplie en définissant les données avec une nomenclature qui vous rappellera peut-être certains frameworks JS :

<Twig:Component :prop="prop">

Il est évidemment possible de fournir des variables par défauts aux composants, et étant donné qu’ils sont déclarés dans votre namespace App, ils sont disponibles en AutoWiring ! On peut même faire des tests dessus grâce au trait InteractWithTwigComponents.

Enfin, Felix nous a parlé des LiveComponents, qui sont finalement une surcouche des TwigComponent, inspirée de Livewire, et qui permet de modifier la donnée des components en direct sur la page.

Écrire du PHP avec seulement 6 caractères

Benoit Viguier est revenu sur scène pour une présentation humoristique, presque digne d’un one-man show. Vous connaissez peut-être les défis consistant à écrire un jeu avec le moins de code possible (JS1K). Il existe un challenge similaire où l'objectif est d'écrire du code en utilisant un nombre minimal de caractères.

Sous contrainte, on devient plus créatif ! C’est le mantra de Benoît, que nous partageons également. Il s'est donc lancé dans ce défi, avec pour objectif de résoudre le challenge en PHP. Non seulement il y est parvenu, mais il a réussi à le faire en seulement 5 caractères ! 👏

Grâce à une accumulation de hacks, tous plus ingénieux les uns que les autres, il est effectivement possible d'écrire du PHP en utilisant seulement 5 caractères. Nous aurions aimé vous montrer un simple echo 'bonjour';, mais le code généré pèse 240 Ko 😅. Pour satisfaire votre curiosité, voici un aperçu du début du fichier :

((((9999999999).(9))^(((((9).(((9^9).(9))^(((9)^(99)).(9))^((9).(9))))^((9).(9^9))^((9^9).(9^9)))^(9^9)).((((99^((9^((9^9)^((9).((9^9))))).(9^9))).(9))^...

Si cela vous intrigue, vous pouvez consulter les slides pour découvrir comment c'est possible !

Webhooks at scale

Lors de son talk, Fabien Paitry a présenté les défis rencontrés par Yousign pour gérer les webhooks face à une forte augmentation de trafic sur leur API.

Chaque jour, l’API Yousign envoie environ 120 000 webhooks avec des temps de réponse variables selon les clients, allant de quelques millisecondes à plusieurs secondes. Le délai maximal de réponse est fixé à 10 secondes pour s'assurer de la compatibilité avec tous les clients. Les webhooks sont gérés de façon asynchrone via RabbitMQ et traités par des workers Symfony. Toutefois, certains clients envoient des demandes de signature par batch (par exemple 1 000), et si un endpoint ne répond pas, avec un retry de 10 secondes, le temps de traitement cumulé peut atteindre les 10 000 secondes, de quoi saturer la queue et ne plus pouvoir dépiler les messages dans un temps raisonnable.

La solution quick and dirty ? Augmenter le nombre de workers. Mais Fabien rappelle que ce n’est pas scalable à l’infini et décrit plutôt les actions mises en place avec son équipe.

Fail fast policy

Première action, réduire le timeout à 1 seconde (temps de réponse moyen de 97% de leurs endpoints) lors du premier appel au webhook. Easy win ! Cela permet d’avoir un plus gros débit sur la queue principale et une meilleure granularité avec une queue dédiée au retry.

Circuit breaker

Deuxième solution adoptée, implémenter le pattern circuit breaker. L’idée est qu’il est inutile de retenter d’appeler directement un serveur distant qui ne répond pas ; il est préférable de réessayer plus tard. Le pattern a 3 états :

Ouvert : le serveur distant est indisponible, aucun appel n'est effectué pendant une période définie ;
Semi ouvert : une seule requête HTTP est envoyée pour vérifier la disponibilité du serveur ;
Fermé : si la requête réussit, le circuit se referme et l’ensemble du trafic est à nouveau autorisé.

Et à l’inverse, si le circuit est fermé mais que le nombre d'appels échoués atteint un seuil critique, il passe à l'état ouvert, stoppant ainsi temporairement les appels sur ce nom de domaine.

En PHP, la bibliothèque Ganesha implémente ce pattern et dispose d’une intégration avec le HttpClient de Symfony.

Covariance, Contravariance et Diamant

À travers de nombreux exemples de code usant (entre autres) d’abstraction et d’héritages, Alexandre Daubois nous montre comment élargir ou réduire les types utilisés en arguments, en valeur de retour, etc.

Ces exemples reposent notamment sur deux des 5 principes SOLID : le principe d’inversion de dépendance et le principe de substitution de Liskov.

Ce sujet assez technique peut difficilement être résumé ici mais nous vous invitons à vous pencher sur les slides qui sont une mine de bons exemples.

Alexandre en a profité pour aborder un autre sujet : l'héritage multiple, et le problème du diamant (aussi appelé problème du diamant de la mort, parce que les informaticien.ne.s ne sont pas dramatiques du tout).

Encore une fois, en utilisant intelligemment les traits et l’héritage, Alexandre nous montre comment résoudre ce genre de problème - nous vous invitons à voir ses slides !

Découverte de Castor : Le Task Runner PHP qui Simplifie votre Workflow

Grégoire Pineau, core contributeur à Symfony, est venu nous présenter Castor 🦫. Si vous suivez régulièrement notre blog, vous connaissez déjà cet outil open source de task running. Castor est conçu pour être simple et facile à prendre en main, avec une expérience développeur optimisée. Il est fourni avec une collection d'outils et de nombreux points d'extension, ce qui permet de l'adapter parfaitement à vos besoins.

Pour en savoir plus, vous pouvez consulter les slides ou lire notre article dédié à ce sujet.

Dis Siri, mets des éléPHPants dans ma domotique

David Buros, développeur chez nos copains de MonsieurBiz, nous a parlé d'un sujet qui n'a pas souvent été abordé aux conférences PHP, mais dont certains d'entre nous sont particulièrement friands à JoliCode : la domotique.

Il a ainsi présenté le fonctionnement de sa domotique qui se base sur Home-Assistant. Ce logiciel, open source et gratuit, a l'avantage de proposer des intégrations avec la plupart des services existants (assistants Google/Siri/etc, produits connectés grand public comme Philips Hue, Ikea, et bien d'autres encore). David nous rappelle les deux fonctions principales de Home-Assistant : afficher les entités dans des dashboard (aka toutes les valeurs / états de tous les appareils reliés à notre domotique) et nous permettre de créer des automatisations (pour réagir aux changements d'états des entités, mais pas que).

David nous a parlé de quelques exemples qu'il a mis en place chez lui, avec par exemple la remontée de sa consommation électrique en temps réel, l'utilisation de micro-module pour contrôler des prises ou des interrupteurs, etc.

L'occasion de parler des protocoles Zigbee et MQTT qui sont souvent employés en domotique. Ainsi, David a pu faire son propre module PHP qui interroge une API tierce, puis envoie les données en MQTT à sa domotique. Une bonne idée pour bidouiller sa domotique sans avoir à faire de python (le langage dans lequel est écrit Home-Assistant).

Le Zéro Downtime Deployment en pratique

Smaïne Milianni, engineering manager chez Yousign, nous a montré les techniques qu'ils utilisent pour s'assurer d'avoir des déploiements sans downtime.

Ils mettent bien sûr en place la méthodologie du Blue-Green Deployment mais dans ce talk il nous donne leurs pro-tips pour le faire bien 💪

L'idée du Zéro Downtime Deployment (ou ZDD), c'est de pouvoir faire des releases transparentes pour les utilisateurs (sans impact, et pas de page "maintenance en cours"), n'importe quand (même un vendredi), mais aussi d'avoir des rollback faciles et rapides quand quelque chose se passe mal. À l'extrême, Smaïne nous montre l'exemple d'une société qui a un rollback automatique qui se fait en 4 minutes si la nouvelle version génère des anomalies ou des erreurs sur Sentry.

Mais pour parvenir à faire du ZDD, le blue-green deployment ne suffit pas. Nous avons également besoin de respecter plusieurs règles. Par exemple, tous les changements doivent être backward compatibles, c'est-à-dire compatible avec la version N actuellement en prod. Dans le cas où l'on veut ajouter une colonne "not nullable" à une table existante, on va devoir procéder en 2 temps :

On ajoute la colonne en nullable dans une release 1, et le code commence à remplir ce nouveau champ
Puis dans une release 2, on update les lignes existantes dont la valeur est encore null et on enlève la contrainte nullable.

La même logique est extrapolable pour le delete, l'update ou le rename d'une colonne. Smaïne a même développé un bundle eniams/safe-migrations qui permet de vérifier que nos migrations sont bien "ZDD-compliant".

Lorsque l'on utilise rabbitMQ, il faut également penser à couper le worker pendant le déploiement. Ainsi les messages vont s'accumuler en version N dans les queues. Donc si nous voulons ajouter une nouvelle propriété à nos messages, il faut le faire avec une valeur par défaut. Cela permettra aux messages en version N d'être désérialisés sans soucis par Messenger avec le code de la version N+1.

Les mêmes problématiques existent lorsque l'on a une application frontend dissociée du code du backend. Si on souhaite ajouter une nouvelle propriété dans une ressource de l'API, il faudra le faire en deux temps, comme pour une modification de la BDD.

Pour finir, Smaïne nous rappelle que le ZDD n'est pertinent que si l'on déploie fréquemment (et ça devrait probablement être le cas 😇) et qu'il nécessite de la réflection et une bonne discipline pour l'équipe de développeurs. Et le ZDD n'évitera pas non plus les down-times lors de changements critiques de l'application. Il ne faut donc pas hésiter à bien éduquer l'équipe, faire de la documentation sur les différents processus ainsi que faire des post-mortems pour apprendre de nos erreurs après des soucis. Retrouvez ses slides sur son site.

WordPress : une cause perdue ?

Cyrille Coquard commence sa conférence avec une question choc : est-ce que WordPress est "de la merde" ? 💩

En effet le code et certains fonctionnements du CMS peuvent être critiqués, mais WordPress a le mérite de rendre la création de site accessible à tous, tout en gérant une dette technique de 2003.

Pour l'utilisateur, c'est parfait, il y a des thèmes, des extensions, Gutenberg (l'éditeur de bloc) et de supports et de tutoriels.

Et puis ensuite il y a la frontière du développement pour les besoins spécifiques. Créer ses propres plugins, gérer les dépendances, les mises à jour... Sans s'outiller correctement c'est vite un enfer.

Il nous a montré qu'on pouvait :

tester nos plugins avec phpunit 🎉 ;
installer nos dépendances avec composer et même gérer les conflits de dépendances avec les autres plugins (voir les librairies mozart et strauss) ;
avoir un event dispatcher orienté objet pour manipuler les hooks de WordPress.

Malheureusement le code des slides n'était pas lisible par l'audience ; ce que nous retenons est qu'il est possible de livrer du code moderne dans WordPress, d'avoir une architecture respectant les bonnes pratiques actuelles : il faut simplement aller voir ailleurs que dans la documentation officielle ! Cyrille a édité son propre socle technique, le projet open-source Launchpad.

Nous regrettons que le drama WP Engine / Automattic n'ait pas été abordé non plus ! 🍿 Il met en péril l'écosystème si riche de WordPress.

Utiliser un framework pour écrire de la documentation ? 📖

Dans le contexte d'une boîte qui grandit, de plus en plus de développeuses et développeurs rejoignent l’équipe technique. Très vite, la nécessité d’un vocabulaire commun, et donc d’une solide documentation se fait sentir. Martin Supiot a tenu à compléter cette documentation qui était très faible et nous donne son retour d’expérience sur le sujet.

Il a pris quelques développeurs et ils ont analysé la documentation : un retour surprenant, la documentation n’était pas seulement difficile à utiliser, elle était également… pas simple à écrire ! 😨

Alors c'est quoi leur processus d'écriture ? Ici on ne va parler que documentation technique, ainsi que de documentation informationnelle, donc qui explique ce qui existe actuellement.

Ils utilisent le framework Dàtaxis, un framework pensé pour les lecteurs. Les documents créés s’articulent autour de quatre axes :

Les explications : elles clarifient un sujet, facilitent la compréhension, expliquent un contexte ;
Les tutoriels : ils permettent l’apprentissage, apportent de la confiance ;
Le how-to guide : il est axé sur un objectif précis, souvent une action répétitive ;
Les références : c’est comme le swagger d'une Api. Elles informent sur tous les paramètres qui existent, les options possibles etc.

Comment nommer ces documents ? Le titre doit être simple, clair, efficace. Quand on lit le nom du document, on doit tout de suite comprendre ce qu'il y a dedans. Pour faire simple, les titres peuvent commencer par :

"Pourquoi …" s’il s’agit d’une explication ;
"Comment …" pour les tutoriels et les how-to ;
"Les différents …" lorsqu’on fait des références.

Ce framework offre également la possibilité d'avoir des templates de documentation. Martin nous donne pas mal de conseils pour un documentation de qualité et bien maintenue :

Ajouter des guidelines afin d’aider ses équipes à documenter ;
Savoir à quelle audience on s’adresse : développeur.se.s front ? Back ? Graphistes ? Product Owner ?
Définir des outils (comme Mermaid, ou draw.io) ;
Faire attention au formatage, à la ponctuation ;
Revenir régulièrement sur la documentation pour la garder à jour, surtout les how-to ;
Trouver un relecteur, et définir des mainteneurs pour chaque fichier, qui seront en charge d’effectuer le point précédent par exemple ;
Supprimer les documents qui ne sont plus à jour.

Et bien sûr, il ne faut pas oublier de documenter la documentation ! Cela pousse les autres à écrire de la documentation technique. Martin en a fait l’expérience et les résultats ont été très satisfaisants : toutes les équipes se sont mises à consulter et rédiger beaucoup plus de documentation depuis qu’il l’a lui-même documentée !

Merci l'AFUP

Pour conclure, nous voulons remercier très très fort l'ensemble des bénévoles de l'AFUP, les speakers, Amélie et tous les sponsors qui ont rendu cet événement possible. C'est une organisation de dingue pour offrir au public ces deux journées de PHP, et nous avons adoré y assister.

À bientôt et bravo aux lecteurs qui sont arrivés jusque là ! Nous espérons que ces récapitulatifs vous sont utiles et que vous avez pu y apprendre autant que nous ! 💕