DEV Community: Thérage Kévin

Construire un assistant de code review RAG avec PHP, Ollama et Qdrant

Thérage Kévin — Tue, 11 Aug 2026 13:48:53 +0000

Les LLM sont excellents pour produire des code reviews qui sonnent juste. Mais « sonner juste » n'est pas la même chose qu'être utiles. Une review qui vous dit de « corrige le Code Style » est correcte mais inutile — chaque projet applique Code Style qui peut différer.

Symfony a plus de 20 ans de code reviews publiques sur GitHub. Chaque PR mergée contient des commentaires de nicolas-grekas, stof, dunglas, xabbuh, et des dizaines d'autres reviewers de la core team et de contributeurs. C'est une mine d'or de patterns de review spécifiques au domaine : quels arguments convainquent, quels patterns sont rejetés, ce que la communauté considère comme du bon code Symfony.

Le problème ? Personne n'avait construit de moteur de recherche pour l'exploiter. Alors je l'ai fais 🤣.

Le lore derrière cette idée folle

Cette histoire prends sa source au Symfony Live de Paris. Comme vous l'imaginez, celui de cette année était très orienté IA. J'ai vu bon nombre de Talks en parlé et j'ai voulu jouer un peu avec cette nouveautée mais jusque là, je n'avais pas de cas concrét.

J'y ai assisté au un Talk de Grégoire Pineau ou il expliquais comment avec Symfony AI, Clickhouse et redirection.io il avait mené à bien la migration d'un site E-Commerce en réduissant la perte de trafic.

Plus tard est arrivé le Console Bundle.

J'avais déjà demandé à un LLM de relire les modifications que j'avais faites (sur des projets perso bien sûr) et, comme vous vous en doutez, j'ai obtenu des conseils du genre pensez à utiliser l'injection de dépendances, peut-être extraire cette logique dans un service ou pense a vérifier le code style. Ces retours sont techniquements corrects, mais surtout universellements applicables et complètements génériques. Bref, rien qui ne puisse être corrigé avec de bons outils et un peu de rigeur.

Sortant du Symfony Live, m'est venu une idée un peu dingue.
Et si je pouvais demander au même LLM :

« Review ce code comme le ferait stof »

J'aurais des retours ultra pointu et un code qui en ressortira grandi.

« Review ce code comme le ferait n'importe quel contributeur Symfony »

J'aurais alors le point de vu de l'ensemble de la communauté sur le code que je viens de créé.

Ou bien même

« Review ce code comme le ferait n'importe quel membre de la core team Symfony »

J'aurais un panel d'experts à ma disposition pour m'expliquer ce qui ne vas pas dans ce que j'ai fait.

C'est ce que fait Symfony Reviewer MCP : un moteur de recherche sémantique (RAG) sur l'ensemble des code reviews historiques de Symfony accessibles via l'API GitHub, exposé via le Model Context Protocol (MCP) le tout avec Symfony AI et dans une application Symfony HTTP-Less.

Je l'ai construit en PHP 8.5 avec Symfony 8.1, utilisant Ollama en local pour la vectorisation avec un model issu de huggingface.co (embeddinggemma-300m, 768 dimensions) et Qdrant comme base de donnée vectorielle.

Aucun GPU requis si on accepte la contrepartie, l'indexation complète des reviews historiques s'est exécutée sur le CPU de ma machine pendant plusieurs jours 😅. Pour un projet ponctuel, ce compromis m'a semblé largement acceptable et "cost-efficient".

Comment ça fonctionne ?

Architecture globale

L'architecture globale se découpe en deux gros blocs :

La génération du RAG :
1. Avec la récupération des données et leurs mise en cache
2. Avec la génération du dataset et l'indexation dans Qdrant
Le serveur MCP

La génération du RAG

Voici le pipeline de génération RAG complet :

Ne vous inquiétez pas si ce schéma paraît dense, je vais parcourir chaque étape du pipeline dans le reste de l'article, depuis la récupération des reviews GitHub jusqu'à la recherche sémantique.

flowchart TD
    A["API GitHub (symfony/symfony)"] --> B["PullsFetcher (PR mergées uniquement)"]
    B --> C["ReviewsFetcher (commentaires + réponses)"]
    C --> D["DatasetGenerator (var/dataset/pull-{id}.txt)"]
    D --> E["Builder::build"]
    E --> F["Ollama (embeddinggemma-300m)"]
    F --> G["Qdrant (collection: reviews)"]

Récupération des données

Avant que toute cette mécanique de décorateurs HTTP ait de l'importance, il faut d'abord parcourir l'API GitHub et décider ce qui mérite d'être gardé.

PullsFetcher pagine GET /repos/symfony/symfony/pulls?state=all&per_page=100, en ne gardant que les PR dont merged_at n'est pas nul — inutile d'entraîner le système sur des idées rejetées. Plutôt que de paginer aveuglément jusqu'à tomber sur une page vide, il envoie d'abord une unique requête HEAD et lit le nombre total de pages directement dans le header Link. Cet appel HEAD est d'ailleurs exactement la raison d'être de BLACKLISTED_PATTERN : c'est une requête de découverte, pas quelque chose qui mérite d'être caché 365 jours.

ReviewsFetcher parcourt ensuite GET /repos/symfony/symfony/pulls/{id}/comments pour chaque PR et reconstruit le véritable arbre de conversation — les commentaires parents avec leurs réponses attachées. Le piège : l'API GitHub ne garantit pas l'ordre des commentaires. Si une réponse arrive avant son parent, ReviewsFetcher la met de côté dans un pool temporaire ($repliesTempPool) au lieu de la perdre, et la rattache dès que le parent est trouvé. Un petit détail de tenue de registre, mais sans lui, n'importe quel thread où trois personnes se disputent sur tabs vs espaces dans le désordre perdrait silencieusement des réponses.

La chaîne de décorateurs HTTP : Logging & Caching

L'architecture

Les deux fetchers passent par la même petite chaîne de décorateurs HTTP :

flowchart TD
    A["GithubHttpClient (scoping + auth Bearer)"] --> B["CachedHttpClient (cache filesystem, TTL 365j)"]
    B --> C["LoggedHttpClient (logging structuré)"]
    C --> D["HttpClient::create() (Symfony natif)"]

Chaque décorateur ajoute une responsabilité :

final readonly class CachedHttpClient implements HttpClientInterface, ResetInterface
{
    public function __construct(
        private HttpClientInterface $client,
        private FilesystemAdapter $cache,
        private LoggerInterface $logger,
        private array $blacklistedPatterns = [],
    ) {
    }

    public function request(string $method, string $url, array $options = []): ResponseInterface
    {
        $pattern = array_map(static fn (string $pattern): string => preg_quote($pattern, '#'), $this->blacklistedPatterns)
            |> (static fn ($x): string => implode('|', $x))
            |> (static fn (string $x): string => \sprintf('#^%s$#', $x))
        ;
        $httpCall = $method.' '.$url;
        if (preg_match($pattern, $httpCall, $matches)) {
            return $this->client->request($method, $url, $options);
        }

        $key = md5($method.$url);
        $cacheItem = $this->cache->getItem($key);
        if ($cacheItem->isHit()) {
            return $cacheItem->get();
        }

        $response = new CachedResponse($this->client->request($method, $url, $options));

        $cacheItem->set($response);
        $this->cache->save($cacheItem);

        return $response;
    }
}

Le problème de sérialisation en chemin

Cette chaîne contient un piège que j'ai déjà documenté dans mon article précédent — HttpClient::getInfo() de Symfony contient une clé pause_handler avec une Closure, impossible à sérialiser. La classe CachedResponse gère cela en filtrant les valeurs non sérialisables :

final readonly class CachedResponse implements ResponseInterface
{
    private int $statusCode;

    /** @var array<string, list<string>> */
    private array $headers;

    private string $content;

    /** @var array<string|int, mixed> */
    private array $toArray;

    /** @var array<string|int, mixed> */
    private array $info;

    public function __construct(ResponseInterface $response)
    {
        $this->statusCode = $response->getStatusCode();
        $this->headers = $response->getHeaders();
        $this->content = $response->getContent();
        $this->toArray = $response->toArray();

        /** @var array<string|int, mixed> $info */
        $info = $response->getInfo();
        $this->info = array_filter($info, static fn ($v): bool => !$v instanceof \Closure);
    }
}

Sans ce filtre, FilesystemAdapter échoue silencieusement — l'exception de sérialisation est attrapée par DefaultMarshaller avec throwOnSerializationFailure à false, et la clé de cache est discrètement ignorée.

Génération du dataset

La commande BuildCommand orchestre le pipeline de vectorisation :

#[AsCommand(
    name: self::NAME,
    description: "build a RAG over Symfony's official Github repository's code review",
    help: 'This command is a pre-requisites for the MCP server',
)]
final readonly class BuildCommand
{
    public const string NAME = 'mcp:build';

    public function __construct(
        private LoggerInterface $logger,
        private DatasetGenerator $datasetGenerator,
        private Builder $builder,
    ) {
    }

    public function __invoke(
        #[Option(description: 'Skip dataset generation and uses dataset cache', name: 'skip-generation', shortcut: 'G')]
        bool $skipGeneration = false,
        #[Option(description: 'Skip build of dataset cache', name: 'skip-build', shortcut: 'B')]
        bool $skipBuild = false,
    ): int {
        try {
            if (!$skipGeneration) {
                $this->datasetGenerator->generate();
            }

            if (!$skipBuild) {
                $this->builder->build();
            }

            return Command::SUCCESS;
        } catch (\Throwable $throwable) {
            $this->logger->error($throwable->getMessage());

            return Command::FAILURE;
        }
    }
}

Le fichier de base

Une fois les données récupérées, DatasetGenerator transforme chaque PR et ses reviews en fichier texte structuré :

[PULL_REQUEST]
    id: 54321
    author: nicolas-grekas
    author_association: MEMBER
    description:
        [HttpKernel] Fix edge case in exception handling

[REVIEWS]
    [REVIEW_1234]
        replyTo:
        reviewer: stof
        reviewer_association: MEMBER
        file: src/Component/HttpKernel/Event/ExceptionEvent.php
        diff:
            @@ -88,7 +88,7 @@
             public function getThrowable(): ?\Throwable
             {
        comment:
            We should keep the original exception here,
            the wrapper is only for internal use.

        reactions:
            +1: 5
            -1: 0
            laugh: 0
            hooray: 0
            confused: 0
            heart: 0
            rocket: 0
            eyes: 0

Ces fichiers vivent dans var/dataset/pull-{id}.txt et servent de vérité terrain pour la vectorisation.

Intégration Qdrant

La base vectorielle est câblée dans le conteneur comme StoreInterface, via le StoreFactory de Qdrant :

->set(StoreInterface::class, Store::class)
    ->autowire()
    ->factory(StoreFactory::create(...))
    ->args([
        '$collectionName' => 'reviews',
        '$endpoint' => env('QDRANT_DSN'),
        '$httpClient' => service(LoggedHttpClient::class),
        '$embeddingsDimension' => 768,
        '$embeddingsDistance' => 'Cosine',
    ])

->set(VectorizerInterface::class, Vectorizer::class)
    ->autowire()
    ->args([
        '$model' => 'hf.co/ggml-org/embeddinggemma-300m-qat-q8_0-GGUF:Q8_0',
    ])

Deux détails valent le détour.

Le Vectorizer utilise exactement le même modèle Ollama qu'au build — un modèle d'embedding hf.co/ggml-org/embeddinggemma-300m-qat-q8_0-GGUF:Q8_0 produisant des vecteurs à 768 dimensions. Cette partie est extrêment importante si vous ne voulez pas vous retrouver à comparer des pommes de terre avec des choux lors de la recherche via le MCP. En effet, un vecteur généré avec un modèle précis ne peux pas être comparé avec un vecteur généré avec un autre modèle.
La base réutilise le décorateur LoggedHttpClient, donc chaque aller-retour vers Qdrant bénéficie d'un logging structuré par-dessus le client HTTP natif de Symfony.

Vectorisation et stockage

C'est là que les choses se gâtent, cette partie à elle seule m'a pris des jours.

Qu'est qu'il se passe à la vectorisation ?

Le fichier issu de var/dataset/pull-{id}.txt sont lus puis envoyés a Ollama pour demander à un modèle d'embedding, dans mon cas hf.co/ggml-org/embeddinggemma-300m-qat-q8_0-GGUF:Q8_0, qui va en générer un vecteur de 768 dimensions (chiffre qui dépends du modèle d'embedding) avant d'être renvoyé à symfony-ai par Ollama pour enfin être sauvegarder dans un espace vectoriel dans Qdrant

sequenceDiagram
    participant AI as Symfony AI (Builder)
    participant Ollama
    participant Model as embeddinggemma-300m
    participant Qdrant

    AI->>Ollama: vectorize(contenu du fichier dataset)
    Ollama->>Model: inférence du modèle
    Model-->>Ollama: 768 valeurs flottantes
    Ollama-->>AI: Vector (768 dimensions)
    AI->>Qdrant: add(VectorDocument)
    Qdrant-->>AI: confirmation

Exemple de vecteur :

❯ ollama run hf.co/ggml-org/embeddinggemma-300m-qat-q8_0-GGUF:Q8_0 'Hello world !'
[0.058340553,0.017256556,-0.0023928124,0.062416226,-0.019779362,-0.069838926,0.003351966,0.029903421,0.01617497,0.009088458,-0.024585545,-0.07013172,0.0077750348,0.03643439,-0.02245716,0.02035499,0.005985676,0.008291158,0.013118213,-0.074038,0.014411658,0.011837681,0.027627029,-0.008276582,0.059961967,0.018847544,0.040701613,0.020481525,0.004880007,-0.026033,0.028065553,-0.015691148,-0.06859542,-0.04025022,-0.0046045044,-0.033632968,0.01929922,0.01854895,-0.000545488,-0.37636346,0.05929959,0.0069747632,-0.026434837,0.018491298,-0.00945082,0.0009028575,0.024641853,-0.053274404,-0.043102805,0.0016308841,-0.04315744,-0.0024387056,-0.007468653,-0.03491168,-0.00315068,-0.023274362,-0.0016503683,-0.027008653,-0.0016653507,0.029124975,0.015810343,-0.020706663,0.03261976,-0.015973076,-0.0104695875,0.0027727042,0.03187403,0.25363848,0.016416604,0.027735965,0.009674886,-0.031506274,-0.01176536,-0.060261074,-0.0031871377,-0.01684568,0.029581062,-0.05600014,-0.02623269,0.04637347,-0.04044786,0.0036846441,0.008154481,0.0190515,-0.023374602,-0.011516434,0.01098124,0.008980432,-0.02016589,-0.020812696,0.046533223,0.009594602,-0.033848874,-0.046110246,0.027529772,0.029260637,-0.04092383,0.00048074988,0.01185442,0.0059498977,0.02239185,-0.0014466406,-0.00841961,-0.011190161,0.05701471,-0.015211558,-0.052781906,0.014623615,-0.0012096912,0.029300302,0.0044483966,0.028927691,-0.032093737,0.048145276,0.034030333,0.03062545,0.015509856,-0.008765529,-0.027545273,0.010858431,0.021899927,-0.008150199,0.0034826857,-0.03487983,-0.039671477,0.009751623,-0.019133179,-0.0030401512,-0.010503486,-0.017615957,0.0365356,0.001852526,-0.013896455,0.04652015,-0.049408674,0.0120107075,0.0065035336,0.0004583914,0.0074103116,-0.028435387,-0.0110742645,-0.0012466233,0.0014801751,-0.015979966,-0.028333941,0.0053472416,0.014286039,0.00054261123,0.049599133,-0.026553018,-0.021315206,0.043478087,0.032634746,0.0031313808,-0.0007238099,-0.0033655402,0.02283678,0.012112167,-0.019739753,-0.0080446005,0.018196804,0.0334649,-0.04168719,-0.0046553654,-0.007058912,-0.0104055125,-0.033779215,0.0015363622,0.051331602,0.009603074,0.0061764405,-0.0047951997,0.0055726245,-0.013255206,-0.0184209,0.025034897,0.057538535,-0.022678796,0.029314326,-0.028992262,-0.024944754,0.005440558,-0.03586656,0.00470333,0.0039566993,-0.03774347,0.007882632,-0.019097507,0.019113457,-0.024320446,-0.012655296,-0.04030833,0.0036063064,0.017062565,-0.047738973,0.03617525,0.009754858,0.01101775,-0.03881582,-0.05497514,0.018249176,-0.02227283,-0.064608485,-0.009161445,-0.010031034,-0.0095641855,0.01916363,0.01516687,0.016545013,-0.002466866,0.05094877,-0.012659827,-0.014525608,-0.023728082,0.043452837,-0.0182468,0.0171756,-0.027970072,-0.07089399,0.030868053,-0.017713076,-0.012257217,-0.010346674,0.026055504,0.0060443725,0.017072264,0.008725935,0.013845085,-0.016069857,-0.015575777,-0.024176376,0.011916211,0.023472574,0.020805132,0.023326341,-0.032767452,-0.054396667,0.013436974,0.004714595,-0.033193223,0.018227011,0.021449534,0.035102192,0.014087173,-0.012364751,-0.02923529,-0.014678346,0.020951372,-0.046659384,-0.0001321898,-0.04854372,-0.008653948,-0.02752997,-0.039902873,0.059013035,-0.023333075,-0.002939849,-0.02412675,-0.004704963,0.005708739,0.0078358585,0.015467018,-0.017394196,-0.024916349,0.0033860407,-0.005256748,-0.019880958,0.02133062,-0.01909998,-0.03368627,-0.030686421,-0.046723425,-0.009353089,0.00718895,0.03141207,-0.005678604,0.010026497,0.017099433,0.09632587,-0.049855407,0.040112875,0.03521583,0.029755611,0.016151456,-0.011640585,-0.012128548,-0.028238969,0.015068383,-0.033082347,0.01045796,0.02537935,0.035929427,-0.066318564,0.0031127778,0.0012862016,-0.0036205864,0.025082638,-0.053492177,-0.0033758928,0.011705148,-0.0033429412,0.04687452,-0.008285868,0.0009990487,-0.032646406,0.009088849,-0.0041933167,-0.046134073,0.0067272885,0.009922917,0.01473402,-0.008017513,-0.042351346,-0.026370844,-0.013365593,-0.05842642,0.0053622974,0.07431096,-0.0013185574,-0.009227675,-0.023330051,-0.027747931,-0.009491263,0.021478329,-0.0059168683,-0.021412537,0.020145044,-0.039623715,-0.0428058,0.025570398,0.03506635,-0.037845273,0.05345302,-0.0574125,-0.00028089757,0.009052639,-0.019611377,0.04223033,0.014607936,0.04443048,0.0076912907,0.007895783,-0.0042047133,-0.0071978727,-0.005284037,0.019756729,0.006555163,0.0008758057,-0.017007992,0.050635543,0.0092563275,0.02716696,0.021407066,0.14517316,-0.02369811,0.0027539528,0.03910237,0.008360229,-0.021910692,0.011394674,0.011142392,-0.0015445971,0.0025348184,0.010536188,0.020002112,-0.025976151,0.02049012,-0.02106826,-0.032985732,0.019664701,0.021935249,0.0066386443,0.017932259,0.01572093,-0.010654519,0.023060553,-0.014906989,0.006019814,0.010056607,0.058398962,-0.033474576,0.0011755938,0.009262606,-0.01099747,-0.0015662273,-0.009874551,0.008189235,0.025591813,-0.018472403,0.04004355,-0.011285104,-0.014111953,-0.0063381894,0.0005300517,-0.023887232,-0.04470202,-0.0028616937,0.014985186,-0.03294004,-0.008383296,-0.043611214,-0.008217752,0.040103037,0.014903076,-0.0021273512,0.042627018,0.0010886613,0.41363978,0.03303489,-0.026918324,-0.051881365,-0.009240305,-0.017186431,-0.064830735,0.019849097,0.033434503,-0.0071105417,0.008766244,-0.017940182,-0.03069124,0.025611496,-0.0054379674,-0.018304668,0.035152443,0.017566781,-0.03807328,0.016257798,0.023560232,0.0043043825,0.08201138,-0.012402507,0.019028682,-0.018637981,0.0073655653,0.0015441499,-0.013527856,-0.0059385803,-0.022364056,-0.02425886,0.016911663,-0.0011785801,0.0053356686,0.016516488,-0.01820115,0.0032703253,-0.012067703,0.020428859,-0.004661816,0.0019089471,0.035107043,-0.04653369,0.032357465,0.037315182,-0.018799154,0.022463702,-0.020647656,0.021579335,-0.0511682,-0.016783282,-0.03466541,-0.0018399828,0.0013000914,-0.010348332,0.0012786519,-0.04518444,0.03560613,0.002523491,-0.005807527,0.010765285,-0.023149451,0.00044260465,0.0029642652,0.0010614877,-0.008083944,-0.022398435,-0.020968962,-0.014627337,0.008090492,0.005585011,-0.03377691,-0.011848554,0.0072662574,-0.03521151,-0.032203663,0.008255807,-0.040369254,0.030274471,-0.011215091,-0.008181156,0.053159524,-0.020998636,-0.002394821,0.0028064605,0.0074562496,0.007893967,-0.007300692,0.0015053308,-0.010529569,-0.0060634767,-0.024756493,-0.03676517,0.011349936,-0.015407753,-0.009043473,0.034528915,0.017980041,-0.021671167,-0.033637524,-0.049074188,-0.010759755,-0.016900545,0.054496538,0.09080891,-0.012992101,0.02599233,-0.0011818404,0.038375963,-0.0099124005,0.010196206,0.013038416,0.0007229094,0.058817368,-0.0010059974,0.031990774,0.05380181,0.024521016,0.002847628,0.07304043,0.0017232046,-0.031101514,-0.0050771832,0.024083985,0.005650839,0.013745816,0.037950784,-0.013184445,-0.030096699,0.0072532697,0.0069977636,0.012731625,-0.03473301,0.020486254,-0.028183239,-0.043638907,0.05255927,0.040101644,0.020626077,-0.00009298259,0.03147282,0.005550194,-0.0030457666,-0.015949357,-0.019966332,0.004474357,0.0073816148,-0.0966872,-0.0014123727,0.015428014,-0.00072764594,0.02582003,0.023952637,-0.013374169,-0.024338745,0.021395741,0.012303337,0.024213506,0.013632532,-0.016449485,-0.03322197,0.0039774035,0.00541838,0.0003197519,-0.031282444,0.021476608,0.006979306,0.024495661,0.008296023,-0.036932785,-0.031137321,-0.00706068,0.024338977,0.0073112054,0.06343152,0.010950803,-0.04011533,0.0023558561,0.005737587,-0.013831569,0.025473805,-0.017996674,0.030670065,-0.021311458,-0.014061837,-0.028316947,-0.016967898,0.05437623,-0.05517407,-0.011666794,-0.064273596,0.00039994833,-0.0016417564,0.00369619,-0.004408155,-0.033399895,0.010705014,0.022728024,-0.006053165,0.0031930788,-0.010684994,-0.05090471,-0.03378601,-0.016370287,0.00020012762,-0.022603909,0.036075003,0.030441662,0.03643664,0.01663764,0.010343481,-0.00867144,-0.015162774,-0.0014251935,0.03770172,-0.013012902,0.035615146,0.00044963427,0.012939211,-0.008898151,0.04329554,0.006962741,0.047645073,-0.058727764,0.0069460804,0.027805299,-0.0022572207,0.03155984,0.007940954,0.025537886,0.026445614,-0.01529072,0.01621024,0.0069643836,-0.013095124,-0.0015153071,-0.013846497,-0.0054590567,0.10567172,0.024595099,-0.021427441,-0.017892607,0.029084895,-0.044227537,-0.020952923,0.0037034317,-0.053684484,-0.026559578,0.0031811807,-0.0022820174,-0.07499727,-0.06748456,-0.031104647,-0.037120227,-0.0070385304,0.03623152,-0.06010997,-0.0040761833,-0.023788461,0.007862985,-0.0080264,0.0294231,-0.06763409,-0.027284352,0.02720548,0.012118604,-0.044641722,0.025212545,-0.0050499276,0.010612783,-0.0048592645,0.011480939,-0.038084067,0.050459232,-0.021653391,-0.016860519,-0.022343304,0.011578441,0.029444221,0.005036281,0.052007847,-0.00015478901,0.010757338,-0.008266853,-0.06438106,0.0038179888,0.010810128,0.014887702,0.041086577,0.09645378,-0.03697137,0.018508574,0.021505969,0.043335702,-0.015699612,0.006846198,0.059496786,0.042588223,-0.020572873,0.0042599905,0.0061774435,-0.0048375144,0.023622885,-0.013585687,0.012436588,-0.0031023244,-0.009659066,0.007284619,0.004994468,-0.03997744,0.025999822,-0.004322784,0.0021907475,0.027662035,0.013451684,0.0061220867,-0.053517137,0.011526667,-0.016668048,0.03389963,0.0024166985,-0.0087329345,0.0005349021,0.09292805,-0.024875147,0.01887172,-0.015814196,0.01548722,-0.0023607062,0.00095323403,0.040603366,-0.018233076,0.00050581084,-0.028851299,-0.05746257,-0.022262363,0.06411007,-0.015622854,0.02921695,0.032788914,-0.0042617223,-0.0026337528,0.029876161,0.026273958,-0.048925456,-0.014354729,0.0069950293,-0.046119038,-0.0015572214,-0.01648194,-0.018696893,-0.036625963,-0.0049027205,-0.002610518,-0.046027448,0.02675758,-0.033888668,0.0046032025,-0.017866787,-0.016139796]

Pourquoi une approche séquentielle ?

Comme expliqué en introduction, sans GPU dédié, c'est mon CPU — plus précisément l'iGPU intégré à mon CPU — qui doit faire le travail de vectorisation.
Même si l'iGPU partage la RAM avec le CPU et bien que 32 Go soient disponibles (modulo l'utilisation de mon système, de programme en cours, ...), la vitesse de la RAM n'a rien à voir avec la mémoire des cartes graphiques, bien plus rapide et dédiée.
De plus, le CPU ne peut traiter que quelques opérations en parallèle, là où le GPU en exécute des milliers simultanément ce qui fait que les calculs matriciels deviennent très lents et mobilisent ma machine à 100%.

Résultat, une seul vectorisation n'est possible à la fois.
Et donc, oui, un batch upsert serait plus rapide, mais le but était de construire un pipeline fonctionnel avec uniquement des ressources locales.

Ce n'est pas une limite de PHP ou de Qdrant, seulement un compromis pragmatique lié au matériel disponible.

Atomicité par renommage de fichiers

C'est la décision de design la plus intéressante. Au lieu d'une table en base de données pour suivre les fichiers traités, le Builder utilise des rename() atomiques :

pull-{id}.txt               → prêt à traiter
processing_pull-{id}.txt    → en cours de vectorisation
ragged_pull-{id}.txt        → vectorisé avec succès

public function build(): void
{
    $this->store->setup(); // ManagedStoreInterface

    $this->recoverOrphanedProcessingFiles();

    foreach (scandir($this->datasetDirectory) as $file) {
        if ('.' === $file || '..' === $file
            || str_starts_with($file, self::RAGGED_PREFIX)
            || str_starts_with($file, self::PROCESSING_PREFIX)) {
            continue;
        }
        if (!rename($this->datasetDirectory.'/'.$file, $this->datasetDirectory.'/'.('processing_'.$file))) {
            continue; // un autre processus l'a pris
        }

        try {
            $content = file_get_contents($this->datasetDirectory.'/processing_'.$file);
            $vector = $this->vectorizer->vectorize($content);
            if (768 !== \count($vector->getData())) {
                throw new \RuntimeException('Wrong dimensions');
            }

            $this->store->add(new VectorDocument(
                id: (int) preg_replace('/[^0-9]/', '', $file),
                vector: $vector,
                metadata: new Metadata(['content' => $content]),
            ));

            rename($this->datasetDirectory.'/processing_'.$file, $this->datasetDirectory.'/ragged_'.$file);
        } catch (\Throwable $e) {
            rename($this->datasetDirectory.'/processing_'.$file, $this->datasetDirectory.'/'.$file); // rollback
        }
    }
}

Crash-safe par conception : si le script meurt en plein milieu, recoverOrphanedProcessingFiles() remet en file les orphelins processing_* au prochain lancement. Pas de locks, pas de base de données, pas de race conditions.

Oui, le code montre que, malgrés ce que j'ai dis plus haut :

Résultat, une seul vectorisation n'est possible à la fois.

Oui, j'ai quand même essayé 🤣.

Utilisation

La CLI expose deux commandes :

# Pipeline complet : récupération → dataset → vectorisation
php bin/console mcp:build

# Re-vectoriser sans re-récupérer
php bin/console mcp:build --skip-generation

# Re-récupérer sans re-vectoriser
php bin/console mcp:build --skip-build

Le serveur MCP

Pour que le LLM puisse avoir accès a ces review fraichement indéxés et effectuer ses recherches lui même, il faut lui donner les accès.
Tout ça s'effectue via le protocole MCP suivant ce pipeline d'appel simplifié :

flowchart TD
    H["Appel Tool MCP (review_as_group/person)"] --> I["Retriever (recherche sémantique)"]
    I --> G["Qdrant (collection: reviews)"]
    I --> J["Client LLM (Claude Desktop)"]

Le pipeline de génération (récupération → dataset → vectorisation) et le pipeline de service (recherche → réponse) partagent un seul point commun : la collection Qdrant.

Le serveur MCP expose deux tools et quatre prompts :

Tool	Rôle
`review_as_group`	Recherche par groupe d'affiliation (MEMBER, CONTRIBUTOR, NONE)
`review_as_person`	Recherche par reviewer spécifique (nicolas-grekas, stof, etc.)

Prompt	Rôle
`review_as_group`	Message formaté utilisant `review_as_group`
`review_as_person`	Message formaté utilisant `review_as_person`
`get_stofed`	Force le reviewer à « stof » — le plus prolifique reviewer du Core Symfony
`hq_review`	Multi-review : interroge 14 reviewers et synthétise un rapport markdown

Recherche : les Tools MCP

Quand un utilisateur envoie une requête via un tool MCP, voici ce qui se passe :

Le tool construit une requête combinant reviewer, chemin de fichier et diff
RetrieverInterface::retrieve() vectorise la requête via Ollama
Une recherche par similarité cosinus s'exécute sur Qdrant
Les VectorDocument correspondants sont retournés
Leur metadata['content'] est extrait et assemblé en contexte

sequenceDiagram
    participant Client as Claude Desktop
    participant MCP as Serveur MCP (stdio)
    participant Tool as review_as_person
    participant Retriever
    participant Ollama
    participant Qdrant

    Client->>MCP: call_tool(review_as_person)
    MCP->>Tool: __invoke(pseudonym, file, diff, limit)
    Tool->>Retriever: retrieve(query, ['limit' => limit])
    Retriever->>Ollama: vectorize(query)
    Ollama-->>Retriever: vecteur de la requête
    Retriever->>Qdrant: recherche par similarité cosinus
    Qdrant-->>Retriever: documents les plus proches
    Retriever-->>Tool: VectorDocument[]
    Tool-->>MCP: reviews trouvées (texte)
    MCP-->>Client: résultat du tool

#[McpTool(
    name: self::NAME,
    description: 'Tool retrieving a `limit` amount of reviews from `pseudonym` github user based on a given git a complete `file` path and `diff`. Results are separated by `\n\n---\n\n`.',
    annotations: new ToolAnnotations('Review matching file diff as github user', true, false, true, false)
)]
final readonly class ReviewAsPersonMatchingFileDiffTool
{
    public const string NAME = 'review_as_person';

    public function __invoke(string $pseudonym, string $file, string $diff, int $limit): string
    {
        $query = <<<TXT
        reviewer: $pseudonym
        file: $file
        diff:
        {$diff}
        TXT;

        try {
            $retrieved = $this->retriever->retrieve($query, ['limit' => $limit]);

            $return = [];
            foreach ($retrieved as $document) {
                $content = $document->getMetadata()['content'] ?? null;
                if (null === $content || !\is_string($content)) {
                    continue;
                }
                $return[] = $content;
            }
        } catch (\Throwable $exception) {
            return 'Error retrieving reviews: '.$exception->getMessage();
        }

        if (0 === \count($return)) {
            return 'No reviews found.';
        }

        return implode("\n\n---\n\n", $return);
    }
}

Le Prompt HQ Review

Le prompt hq_review est la fonctionnalité vedette. Il interroge 14 reviewers Symfony de premier plan (GromNaN, dunglas, welcoMattic, nicolas-grekas, chalasr, stof, yceruto, mtarld, OskarStark, xabbuh, lyrixx, kbond, jderusse, alexandre-daubois), collecte leurs feedbacks historiques sur le même fichier/diff, et demande au LLM de synthétiser un rapport markdown avec des retours pondérés par reviewer.

Le résultat est une code review qui ressemble à un mini-symposium des mainteneurs du Core Symfony — sans nécessiter leur temps.

Utilisation

docker build -t symfony-reviewer-mcp-cli /path/to/Dockerfile
docker run -i --rm --add-host=host.docker.internal:host-gateway -e QDRANT_DSN=http://host.docker.internal:6333 -e OLLAMA_DSN=http://host.docker.internal:11434 symfony-reviewer-mcp-cli

Puis configurer Claude Desktop (ou tout client MCP) en ajoutant le serveur à claude_desktop_config.json :

{
  "mcpServers": {
    "symfony-reviewer": {
      "command": "docker",
      "args": [
            "run", "-i", "--rm",
            "--add-host=host.docker.internal:host-gateway",
            "-e", "QDRANT_DSN=http://host.docker.internal:6333",
            "-e", "OLLAMA_DSN=http://host.docker.internal:11434",
            "symfony-reviewer-mcp-cli"
        ]
    }
  }
}

Les variables d'env

Toute la configuration passe par les variables .env :

Variable	Rôle
`GITHUB_TOKEN`	Token d'accès personnel GitHub
`QDRANT_DSN`	URL du service Qdrant
`OLLAMA_DSN`	URL du service Ollama
`BLACKLISTED_PATTERN`	Tableau JSON de patterns URL à exclure du cache
`APP_VERSION`	Version affichée dans les métadonnées MCP

Leçons apprises

Ce projet m'a permis de comprendre comment fonctionne le protocole MCP, ce qu'est un base de données vectoriel et comment l'utiliser. L'architecture présentée ici est relativement classique pour un pipeline RAG mais il a été réalisé avec Symfony et peu servir de socle de base pour d'autres expérimentations ou usages.

Ce qui a bien fonctionné

Atomicité par renommage de fichiers : Ce pattern est élégant, crash-safe et ne nécessite aucune infrastructure. Chaque développeur PHP comprend rename(). Pas de locks Redis, pas de migrations de base de données.
Pipeline incrémental : Relancer mcp:build avec des fichiers existants est un no-op. L'itération est rapide — on peut ajuster la vectorisation et ne traiter que les nouveaux fichiers.
Fonctionnalités PHP 8.x : La promotion de constructeur, les propriétés readonly, l'opérateur pipe (|>), et les commandes invokables rendent le code bien plus propre.
Ollama en local : embeddinggemma-300m tourne sur CPU sans problème. 768 dimensions, c'est assez modeste pour des requêtes rapides mais assez riche pour la recherche sémantique sur des code reviews.

Ce qui doit être amélioré

Si j'avais eu une machine plus efficace avec un GPU dédié ou une RAM unifiée (👋 les propriétaires de Mac), j'aurai peut-être pu changer ce qui suit :

Interaction Qdrant naïve : Les documents sont ajoutés un par un. Un batch upsert serait nettement plus rapide pour les gros volumes.
Pas de mise à jour incrémentale du RAG : Le pipeline est add-only. Il n'y a pas de mécanisme "builtin" (c'est possible via le dashboard de qdrant) pour purger ou mettre à jour les vecteurs existants quand des commentaires de PR sont édités sur GitHub. Ce qui en soit est un vrai/faux problème puisqu'on retrouve rarement de nouveaux commentaire sur des Pull-Requests déjà mergées.
Ajoutez vos propres conventions : J'ai ajouté les reviews de Symfony, mais vous pouvez vous aussi modifier et adapter le code pour qu'il s'appuie sur un corpus de données supplémentaire comme les revues de vos collaborateurs.

Ce que je ferais différemment

Vectorisation par lots : Grouper les documents et vectoriser en lots pour un meilleur débit
Récupération asynchrone : La phase de récupération des données est séquentielle par PR. Des requêtes concurrentes réduiraient significativement le temps de construction initial
Webhook GitHub : Au lieu de reconstruire périodiquement, écouter les événements de PR mergées et mettre à jour le dataset de manière incrémentale
Évaluation des modèles d'embeddings : 768 dimensions fonctionne bien, mais je devrais comparer différents modèles : des modèles plus petits (comme all-MiniLM-L6-v2, 384 dimensions) pour améliorer les performances, ou des modèles beaucoup plus gros afin d'évaluer le gain potentiel en qualité de recherche.
Contexte élargi : commentaires de PR et diff complet : le dataset actuel ne retient que les review comments attachés à un diff précis. Il ignore les commentaires généraux de la PR (issue comments, description) et surtout le diff complet de la PR — un reviewer ne juge jamais une ligne isolée, il la juge dans le contexte du changement entier. Injecter les deux donnerait au modèle bien plus de matière pour comprendre pourquoi une review a été formulée ainsi.
Exploiter le champ metadata pour le JSON brut de GitHub : symfony/ai-store attache à chaque VectorDocument un objet Metadata (Symfony\AI\Store\Document\Metadata) qui voyage jusqu'au store choisi. Chez Qdrant, ce Metadata correspond exactement à la notion de payload : un objet JSON arbitraire attaché à chaque point, indexable et filtrable nativement — par exemple filtrer par reviewer_association, par date, ou par nombre de réactions, sans re-parser le texte du dataset. Aujourd'hui, seul content (le texte assemblé du fichier dataset) y est stocké ; j'y aurais ajouté la réponse JSON brute de l'API GitHub (PR + review + reactions), pour garder une trace exploitable indépendante du format texte généré.
Exploiter les réactions du JSON GitHub: Les réactions se prêteraient d'ailleurs à mieux qu'un simple filtre : elles pourraient pondérer le score de recherche lui-même, pas juste être renvoyées dans le content. Depuis la version 1.14, Qdrant propose une Formula Query qui permet de composer un score final à partir du score de similarité initial et de champs du payload, dans une même formule de reclassement. Une review avec dix +1 remonterait alors devant une review isolée à zéro réaction, à similarité vectorielle égale — une façon de faire remonter les avis que la communauté a elle-même validés, Une fonctionnalitée qui meriterai d'être explorée.

Est-ce que ça fonctionne ?

La grande question : « est-ce que les reviews produites sont réellement meilleures ? ».

Répondre Oui serait en parti faux. En effet, aujourd'hui, mon évaluation reste essentiellement basée sur un sentiment générale plutôt que sur de vraies données tangibles et quantifiables.
Les réponses générées me paraissent beaucoup plus dans le ton d'une review qui aurait été effectuée sur le dépôt Github de Symfony, et donc plus proches des ses conventions, que les réponses obtenues avec un LLM sans contexte.
Enfin, comme un LLM et par nature "probabiliste", je ne crois pas qu'il soit pertinant de dire que sur la base de mes propres observations et mon sentiment personnel seul le fonctionnement d'un outil est établi.

Voici un exemple de revue effectuée sur ce projet pour vous donner un idée :

---

### 1. fabpot
**Files:** `src/HTTP/CachedHttpClient.php`, `src/HTTP/CachedResponse.php`

> Thanks for the PR! A few things before we can merge:
>
> * Why is the cache key based on the URL only? For `POST` requests the body matters, otherwise all `/api/embed` calls will return the same result. This is a real bug, not an optimization issue.
> * Please add a test covering the "non-buffered" response case — `getContent()` then `toArray()` will fail on `EventSourceHttpClient` responses.
> * Do we need a `CHANGELOG` entry for the `CachedHttpClient`? I think we can keep it internal.
>
> Otherwise the approach is clean. Once the cache key is fixed, we can squash the commits.

---

### 2. nicolas-grekas
**Files:** `src/HTTP/CachedResponse.php`, `src/Kernel.php`

> Reading the response body twice is going to blow up the moment the response is not buffered. `toArray()` internally calls `getContent()` — so snapshot the content once and `json_decode` it, don't call both.
>
> Also, the decorated chain is wrong: `service(LoggedHttpClient::class)` no longer resolves to the logger once you decorate it with `CachedHttpClient`. Qdrant and Ollama are being routed through the GitHub cache without intent. Decorate a dedicated alias, e.g. `cached.github.http_client`, and keep `HttpClientInterface` as the plain chain.
>
> One more: `getContent(false)` is being snapshotted eagerly in the constructor — that defeats lazy streaming for large GitHub responses. Buffer lazily.

---

### 3. stof
**Files:** `src/Kernel.php`

> Service wiring nit: decoration replaces the decorated id, so `$httpClient => service(LoggedHttpClient::class)` gives you the `CachedHttpClient`, not the logging client. That's a scope leak — the Qdrant store is now coupled to a cache tuned for the GitHub API (see `BLACKLISTED_PATTERN`).
>
> I'd define a dedicated `logged.http_client` service for the store/platform and only decorate `cached.github.http_client` for the GitHub fetchers. Also check the `->decorate(..., priority: 1)` priorities — with equal priorities the order of application is by declaration order, which is fragile to read.
>
> And the `json:BLACKLISTED_PATTERN` env var — document its format in the README.

---

### 4. weaverryan
**Files:** `src/MCP/Tools/ReviewAsPersonMatchingFileDiffTool.php`

> Hey! Love the ergonomics of this tool — the `review_as_person` name makes the intent super clear. Great job composing the query with the pseudonym, file, and diff.
>
> One DX thought: when no reviews are found we return `No reviews found.` — that's good. But maybe give the caller a hint that they can reduce `limit` or widen the diff? Small thing, ignore if you want.
>
> Also, the metadata `content` check with the warning log is nice defensive coding. Keep it up! 🎉

---

### 5. derrabus
**Files:** `src/HTTP/CachedHttpClient.php`

> Two things:
>
> 1. `$key = md5($method.$url)` — please include the serialized options/body. Hash collisions here are silent correctness bugs, not just perf issues.
> 2. The `preg_match` on a compiled regex built via pipe chains is clever but hard to read. Since the blacklist is a list of exact strings, why not use `in_array` or a simple `str_starts_with` on the pattern list? Keep it simple.
>
> Also, the code is `final readonly` — good. But it implements `ResetInterface`; make sure the decorated inner `reset()` is reachable in `withOptions()` clones (it is, since you forward to the scoped client — just double-check the cache/lifecycle after cloning).

---

### 6. xabbuh
**Files:** `src/HTTP/CachedResponse.php`

> I have concerns about the snapshot in the constructor:
>
> * Calling `$response->getContent()` eagerly downloads and stores the whole payload. For the GitHub fetchers this is fine, but a general-purpose cache should stream lazily.
> * More importantly, `getContent()` followed by `toArray()` breaks for responses that disabled buffering (the Ollama `EventSourceHttpClient` forces `buffer => false`). This is an exploitable/observable crash — at minimum it should throw a clear `TransportException` or read once.
> * `getInfo()` filtering out closures is a nice touch, but the returned array is shallow — nested closures could still leak. Use a recursive filter or `json_encode/decode` the info array.

---

### 7. Tobion
**Files:** `src/HTTP/CachedHttpClient.php`

> The pipeline operator chains in `request()` are over-engineered for building a regex. `implode('|', array_map(preg_quote(...), $this->blacklistedPatterns))` is enough. As written, an empty blacklist produces the pattern `#^$#` which would match an empty call string — harmless, but misleading.
>
> More importantly: cache invalidation. There is none — responses are cached for a year (`defaultLifetime`). GitHub data changes; the fetchers need a way to bust the cache (e.g. include a version/tag in the key or a TTL per-URL). Otherwise reviews fetched once are served stale forever.

---

### 8. mpdude
**Files:** `src/RAG/Builder.php` (via `Store`)

> The Qdrant indexing loop swallows exceptions and logs `Index failed` — but the build then *continues* (I saw `Indexing document continues`). If a document fails vectorization, subsequent documents are still sent. That means the collection is only partially populated, and `review_as_person` will silently return "No reviews found" or partial results.
>
> Please make the build fail-fast or at least surface a summary count at the end ("indexed X / failed Y") so operators know the dataset is incomplete. Right now nothing tells us that only ~1106 of 8691 documents made it in.

---

### 9. WouterJ
**Files:** `src/Kernel.php`

> The container config reads really well — the decoration chain is easy to follow. Nice use of `env('json:BLACKLISTED_PATTERN')` and `StoreFactory::create(...)`.
>
> Minor: the `logged.http_client` vs `cached.github.http_client` distinction is muddied because both decorators use `priority: 1` and decorate each other's ids. I'd give them explicit service aliases (`github.logged.http_client`, etc.) so the intent is obvious. Also the unused `'stream_handler'` monolog handler and the commented-out `http` transport block could be cleaned up before merge.

---

### 10. alexislefebvre
**Files:** `tests/HTTP/CachedHttpClientTest.php`

> Nice test coverage — you test blacklist skipping, persistence across instances, `withOptions` cloning, and `reset`. 👍
>
> Missing cases I'd love to see:
>
> 1. A `POST` request with a body — assert that different bodies don't collide in the cache (this would catch the `md5(method.url)` bug).
> 2. A non-buffered/streaming response (`MockResponse` with `buffer => false` is hard to fake; but at least an SSE-like response) going through `CachedResponse` without throwing.
> 3. The cache should not be hit for `POST`/`PUT` (or should include the body in the key) — please encode that expectation in a test.

---

### 11. Nyholm
**Files:** `src/HTTP/LoggedHttpClient.php`, `src/HTTP/CachedHttpClient.php`

> As the http-client component maintainer: don't re-implement caching. Symfony's `HttpClient` supports a `cache` option natively via the `http_cache` from the contracts, and it handles cache keys, headers, `Vary`, and ETags properly. Rolling your own `md5(method.url)` cache key is a regression waiting to happen (it already broke on POST bodies).
>
> If you keep the custom decorator, at least delegate to `CacheItemPoolInterface` semantics and include the request payload + relevant headers in the key. And please make `stream()` forward correctly — it does, but note that cached responses can never stream, which may surprise callers.
>
> Also: `FileSystemAdapter` on a single Docker container is fine, but for multi-instance deploys you'll want a shared pool (Redis). Worth a comment.

---

### 12. jderusse
**Files:** `src/RAG/Builder.php`, `src/HTTP/CachedHttpClient.php`

> The elephant in the room: the per-document vectorization loop is serial. 8691 documents, ~10s each — that's ~24h to build the RAG, and with the cache bug most embeddings were identical (same URL → same key). That's why retrieval feels broken.
>
> Fixes I'd push for:
> * Parallelize vectorization with Symfony's `AsyncResponse` / `stream()` over batches.
> * Include the body in the cache key (obviously).
> * Index the docs that failed (`Index failed` ×636) with retry/backoff.
>
> Also `Builder` should checkpoint progress so a crash doesn't restart from zero.

---

### 13. chalasr
**Files:** `src/MCP/Tools/ReviewAsPersonMatchingFileDiffTool.php`, `src/Command/ServeCommand.php`

> Tool ergonomics are good — `limit` is explicit, errors are caught and surfaced. But: the error path returns `Error retrieving reviews: {message}` as a *successful* tool result. For an MCP server, real failures should be proper exceptions/tool errors, not strings, otherwise the client can't distinguish "no data" from "server broken".
>
> Also, the query string embeds the raw diff with no size guard — a huge diff will blow the embedding context window. Truncate or chunk the diff.
>
> And the serve command: make sure `APP_DEBUG` is off in prod and there's a graceful shutdown on SIGTERM.

---

### 14. yceruto
**Files:** `src/Kernel.php`, `src/HTTP/CachedHttpClient.php`

> The routing of the HTTP decorators deserves attention: `LoggedHttpClient::class` is decorated by `CachedHttpClient`, so every consumer referencing it — including the Qdrant store — ends up behind the GitHub cache. That coupling is accidental.
>
> I'd restructure like this:
> ```


> HttpClientInterface          # plain
>  └─ logged.http_client       # logging only (for Qdrant/Ollama)
>  └─ cached.github.http_client # cache + github token (for GitHub fetchers)
>

Two separate chains, no cross-decorating. Then the cache key issue (URL-only, no body) also only affects GitHub GETs, which is safe.

After that, the 14 review_as_person calls will stop returning the buffering is disabled error and start returning real reviews.




## Pour conclure

<div style="width:100%;height:0;padding-bottom:56%;position:relative;">
    <iframe src="https://giphy.com/embed/NRiRXQTwbijNba2l2l" width="100%" height="100%" style="position:absolute" frameBorder="0" class="giphy-embed" allowFullScreen></iframe>
</div>

<p><a href="https://giphy.com/gifs/The-Animal-Crackers-Movie-baking-try-it-NRiRXQTwbijNba2l2l">via GIPHY</a></p>

Essayez-le vous même, le [projet](https://github.com/ktherage/symfony-review-mcp) est conçu pour être autonome et indépendant. Les données sont publiquements accessibles, vous pouvez créé une instance Qdrant et Ollama facilement avec [Docker](https://www.docker.com/).

Pour l'installer :



```bash
git clone https://github.com/ktherage/symfony-review-mcp
cd symfony-review-mcp
docker compose run --rm cli composer install
docker compose run --rm cli bin/console mcp:build
docker compose up -d

La chose la plus surprenante que j'ai apprise en construisant ce projet : PHP est un langage parfaitement viable pour les pipelines RAG. Les composants HttpClient, Cache et Console de Symfony, combinés avec les packages symfony/ai-*, gèrent tout, de la décoration HTTP aux opérations sur bases vectorielles.

Vous n'avez pas besoin de Python pour faire de la recherche sémantique.

Parfois, le meilleur outil pour le travail est celui que vous maîtrisez déjà.

Building a RAG-Powered Code Review Assistant with PHP, Ollama, and Qdrant

Thérage Kévin — Tue, 11 Aug 2026 09:12:11 +0000

LLMs are great at producing code reviews that sound right. But "sounding right" isn't the same as being useful. A review that tells you to "fix the Code Style" is correct but useless — every project applies a Code Style that may differ.

Symfony has more than 20 years of public code reviews on GitHub. Every merged PR contains comments from nicolas-grekas, stof, dunglas, xabbuh, and dozens of other reviewers from the core team and contributors. It's a goldmine of domain-specific review patterns: which arguments convince, which patterns get rejected, what the community considers good Symfony code.

The problem? No one had built a search engine to exploit it. So I did it 🤣.

The lore behind this crazy idea

This story starts at the Symfony Live in Paris. As you can imagine, this year's edition was very AI-focused. I saw quite a few talks about it and wanted to play around with this novelty, but until then I didn't have a concrete use case.

I attended a talk by Grégoire Pineau where he explained how, with Symfony AI, Clickhouse and redirection.io, he had successfully migrated an e-commerce site while reducing traffic loss.

Later, the Console Bundle arrived.

I had already asked an LLM to review the changes I had made (on personal projects of course) and, as you might guess, I got advice like consider using dependency injection, maybe extract this logic into a service or remember to check the code style. These pieces of feedback are technically correct, but above all universally applicable and completely generic. In short, nothing that can't be fixed with good tools and a little rigor.

Coming out of Symfony Live, a somewhat crazy idea came to me.
What if I could ask the same LLM:

"Review this code the way stof would"

I'd get ultra-sharp feedback and code that would come out stronger.

"Review this code the way any Symfony contributor would"

Then I'd get the whole community's point of view on the code I just created.

Or even

"Review this code the way any member of the Symfony core team would"

I'd have a panel of experts at my disposal to explain what's wrong with what I did.

That's what Symfony Reviewer MCP does: a semantic search engine (RAG) over all of Symfony's historical code reviews, accessible via the GitHub API, exposed through the Model Context Protocol (MCP), all with Symfony AI and in a Symfony HTTP-less application.

I built it in PHP 8.5 with Symfony 8.1, using Ollama locally for vectorization with a model from huggingface.co (embeddinggemma-300m, 768 dimensions) and Qdrant as the vector database.

No GPU required — if you accept the trade-off: indexing all historical reviews ran on my machine's CPU for several days 😅. For a one-off project, I found this trade-off largely acceptable and cost-efficient.

How does it work?

Global architecture

The global architecture is split into two big blocks:

RAG generation:
1. Data fetching and caching
2. Dataset generation and indexing into Qdrant
The MCP server

RAG generation

Here is the complete RAG generation pipeline:

Don't worry if this diagram looks dense — I'll walk through every step of the pipeline in the rest of the article, from fetching GitHub reviews to semantic search.

flowchart TD
    A["GitHub API (symfony/symfony)"] --> B["PullsFetcher (merged PRs only)"]
    B --> C["ReviewsFetcher (comments + replies)"]
    C --> D["DatasetGenerator (var/dataset/pull-{id}.txt)"]
    D --> E["Builder::build"]
    E --> F["Ollama (embeddinggemma-300m)"]
    F --> G["Qdrant (collection: reviews)"]

Fetching the data

Before all this HTTP decorator machinery matters, you first have to walk the GitHub API and decide what's worth keeping.

PullsFetcher pages through GET /repos/symfony/symfony/pulls?state=all&per_page=100, keeping only PRs whose merged_at isn't null — no point training the system on rejected ideas. Rather than blindly paging until hitting an empty page, it first sends a single HEAD request and reads the total page count directly from the Link header. That HEAD call is exactly why BLACKLISTED_PATTERN exists: it's a discovery request, not something worth caching for 365 days.

ReviewsFetcher then walks GET /repos/symfony/symfony/pulls/{id}/comments for each PR and rebuilds the actual conversation tree — parent comments with their replies attached. The catch: GitHub's API doesn't guarantee comment ordering. If a reply arrives before its parent, ReviewsFetcher parks it in a temporary pool ($repliesTempPool) instead of dropping it, and reattaches it as soon as the parent is found. A small piece of bookkeeping, but without it, any thread where three people argue about tabs vs. spaces out of order would silently lose replies.

The HTTP decorator chain: Logging & Caching

The architecture

Both fetchers go through the same small HTTP decorator chain:

flowchart TD
    A["GithubHttpClient (scoping + Bearer auth)"] --> B["CachedHttpClient (filesystem cache, 365d TTL)"]
    B --> C["LoggedHttpClient (structured logging)"]
    C --> D["HttpClient::create() (Symfony native)"]

Each decorator adds one responsibility:

final readonly class CachedHttpClient implements HttpClientInterface, ResetInterface
{
    public function __construct(
        private HttpClientInterface $client,
        private FilesystemAdapter $cache,
        private LoggerInterface $logger,
        private array $blacklistedPatterns = [],
    ) {
    }

    public function request(string $method, string $url, array $options = []): ResponseInterface
    {
        $pattern = array_map(static fn (string $pattern): string => preg_quote($pattern, '#'), $this->blacklistedPatterns)
            |> (static fn ($x): string => implode('|', $x))
            |> (static fn (string $x): string => \sprintf('#^%s$#', $x))
        ;
        $httpCall = $method.' '.$url;
        if (preg_match($pattern, $httpCall, $matches)) {
            return $this->client->request($method, $url, $options);
        }

        $key = md5($method.$url);
        $cacheItem = $this->cache->getItem($key);
        if ($cacheItem->isHit()) {
            return $cacheItem->get();
        }

        $response = new CachedResponse($this->client->request($method, $url, $options));

        $cacheItem->set($response);
        $this->cache->save($cacheItem);

        return $response;
    }
}

The serialization problem along the way

This chain contains a trap I already documented in my previous article — Symfony's HttpClient::getInfo() contains a pause_handler key with a Closure, impossible to serialize. The CachedResponse class handles this by filtering out non-serializable values:

final readonly class CachedResponse implements ResponseInterface
{
    private int $statusCode;

    /** @var array<string, list<string>> */
    private array $headers;

    private string $content;

    /** @var array<string|int, mixed> */
    private array $toArray;

    /** @var array<string|int, mixed> */
    private array $info;

    public function __construct(ResponseInterface $response)
    {
        $this->statusCode = $response->getStatusCode();
        $this->headers = $response->getHeaders();
        $this->content = $response->getContent();
        $this->toArray = $response->toArray();

        /** @var array<string|int, mixed> $info */
        $info = $response->getInfo();
        $this->info = array_filter($info, static fn ($v): bool => !$v instanceof \Closure);
    }
}

Without this filter, FilesystemAdapter silently fails — the serialization exception is caught by DefaultMarshaller with throwOnSerializationFailure set to false, and the cache key is quietly ignored.

Dataset generation

The BuildCommand class orchestrates the vectorization pipeline:

#[AsCommand(
    name: self::NAME,
    description: "build a RAG over Symfony's official Github repository's code review",
    help: 'This command is a pre-requisites for the MCP server',
)]
final readonly class BuildCommand
{
    public const string NAME = 'mcp:build';

    public function __construct(
        private LoggerInterface $logger,
        private DatasetGenerator $datasetGenerator,
        private Builder $builder,
    ) {
    }

    public function __invoke(
        #[Option(description: 'Skip dataset generation and uses dataset cache', name: 'skip-generation', shortcut: 'G')]
        bool $skipGeneration = false,
        #[Option(description: 'Skip build of dataset cache', name: 'skip-build', shortcut: 'B')]
        bool $skipBuild = false,
    ): int {
        try {
            if (!$skipGeneration) {
                $this->datasetGenerator->generate();
            }

            if (!$skipBuild) {
                $this->builder->build();
            }

            return Command::SUCCESS;
        } catch (\Throwable $throwable) {
            $this->logger->error($throwable->getMessage());

            return Command::FAILURE;
        }
    }
}

The base file

Once the data is fetched, DatasetGenerator transforms each PR and its reviews into a structured text file:

[PULL_REQUEST]
    id: 54321
    author: nicolas-grekas
    author_association: MEMBER
    description:
        [HttpKernel] Fix edge case in exception handling

[REVIEWS]
    [REVIEW_1234]
        replyTo:
        reviewer: stof
        reviewer_association: MEMBER
        file: src/Component/HttpKernel/Event/ExceptionEvent.php
        diff:
            @@ -88,7 +88,7 @@
             public function getThrowable(): ?\Throwable
             {
        comment:
            We should keep the original exception here,
            the wrapper is only for internal use.

        reactions:
            +1: 5
            -1: 0
            laugh: 0
            hooray: 0
            confused: 0
            heart: 0
            rocket: 0
            eyes: 0

These files live in var/dataset/pull-{id}.txt and serve as the ground truth for vectorization.

Qdrant integration

The vector store is wired into the container as StoreInterface, via Qdrant's StoreFactory:

->set(StoreInterface::class, Store::class)
    ->autowire()
    ->factory(StoreFactory::create(...))
    ->args([
        '$collectionName' => 'reviews',
        '$endpoint' => env('QDRANT_DSN'),
        '$httpClient' => service(LoggedHttpClient::class),
        '$embeddingsDimension' => 768,
        '$embeddingsDistance' => 'Cosine',
    ])

->set(VectorizerInterface::class, Vectorizer::class)
    ->autowire()
    ->args([
        '$model' => 'hf.co/ggml-org/embeddinggemma-300m-qat-q8_0-GGUF:Q8_0',
    ])

Two details are worth mentioning.

The Vectorizer uses exactly the same Ollama model as at build time — an embedding model hf.co/ggml-org/embeddinggemma-300m-qat-q8_0-GGUF:Q8_0 producing 768-dimension vectors. This part is extremely important if you don't want to end up comparing apples with oranges during MCP search. Indeed, a vector generated with a specific model can't be compared with a vector generated with another model.
The store reuses the LoggedHttpClient decorator, so every Qdrant round-trip benefits from structured logging on top of Symfony's native HTTP client.

Vectorization & storage

This is where things get hairy — this part alone took me days.

What happens during vectorization?

The file from var/dataset/pull-{id}.txt is read, then sent to Ollama to ask an embedding model — in my case hf.co/ggml-org/embeddinggemma-300m-qat-q8_0-GGUF:Q8_0 — which generates a 768-dimension vector (a number that depends on the embedding model) before it's sent back to symfony-ai by Ollama, to finally be saved into a vector space in Qdrant.

sequenceDiagram
    participant AI as Symfony AI (Builder)
    participant Ollama
    participant Model as embeddinggemma-300m
    participant Qdrant

    AI->>Ollama: vectorize(dataset file content)
    Ollama->>Model: model inference
    Model-->>Ollama: 768 float values
    Ollama-->>AI: Vector (768 dimensions)
    AI->>Qdrant: add(VectorDocument)
    Qdrant-->>AI: confirmation

Example vector:

❯ ollama run hf.co/ggml-org/embeddinggemma-300m-qat-q8_0-GGUF:Q8_0 'Hello world !'
[0.058340553,0.017256556,-0.0023928124,0.062416226,-0.019779362,-0.069838926,0.003351966,0.029903421,0.01617497,0.009088458,-0.024585545,-0.07013172,0.0077750348,0.03643439,-0.02245716,0.02035499,0.005985676,0.008291158,0.013118213,-0.074038,0.014411658,0.011837681,0.027627029,-0.008276582,0.059961967,0.018847544,0.040701613,0.020481525,0.004880007,-0.026033,0.028065553,-0.015691148,-0.06859542,-0.04025022,-0.0046045044,-0.033632968,0.01929922,0.01854895,-0.000545488,-0.37636346,0.05929959,0.0069747632,-0.026434837,0.018491298,-0.00945082,0.0009028575,0.024641853,-0.053274404,-0.043102805,0.0016308841,-0.04315744,-0.0024387056,-0.007468653,-0.03491168,-0.00315068,-0.023274362,-0.0016503683,-0.027008653,-0.0016653507,0.029124975,0.015810343,-0.020706663,0.03261976,-0.015973076,-0.0104695875,0.0027727042,0.03187403,0.25363848,0.016416604,0.027735965,0.009674886,-0.031506274,-0.01176536,-0.060261074,-0.0031871377,-0.01684568,0.029581062,-0.05600014,-0.02623269,0.04637347,-0.04044786,0.0036846441,0.008154481,0.0190515,-0.023374602,-0.011516434,0.01098124,0.008980432,-0.02016589,-0.020812696,0.046533223,0.009594602,-0.033848874,-0.046110246,0.027529772,0.029260637,-0.04092383,0.00048074988,0.01185442,0.0059498977,0.02239185,-0.0014466406,-0.00841961,-0.011190161,0.05701471,-0.015211558,-0.052781906,0.014623615,-0.0012096912,0.029300302,0.0044483966,0.028927691,-0.032093737,0.048145276,0.034030333,0.03062545,0.015509856,-0.008765529,-0.027545273,0.010858431,0.021899927,-0.008150199,0.0034826857,-0.03487983,-0.039671477,0.009751623,-0.019133179,-0.0030401512,-0.010503486,-0.017615957,0.0365356,0.001852526,-0.013896455,0.04652015,-0.049408674,0.0120107075,0.0065035336,0.0004583914,0.0074103116,-0.028435387,-0.0110742645,-0.0012466233,0.0014801751,-0.015979966,-0.028333941,0.0053472416,0.014286039,0.00054261123,0.049599133,-0.026553018,-0.021315206,0.043478087,0.032634746,0.0031313808,-0.0007238099,-0.0033655402,0.02283678,0.012112167,-0.019739753,-0.0080446005,0.018196804,0... (line truncated to 2000 chars)

Why a sequential approach?

As explained in the intro, without a dedicated GPU, it's my CPU — more precisely the iGPU integrated into my CPU — that has to do the vectorization work.
Even though the iGPU shares RAM with the CPU and even though 32 GB are available (depending on my system usage, running programs, ...), RAM speed has nothing to do with graphics card memory, which is far faster and dedicated.
Moreover, the CPU can only process a few operations in parallel, where the GPU executes thousands simultaneously, which makes matrix computations very slow and saturates my machine at 100%.

As a result, only one vectorization at a time is possible.
And so yes, a batch upsert would be faster, but the goal was to build a working pipeline using only local resources.

It's not a limitation of PHP or Qdrant, just a pragmatic trade-off tied to the available hardware.

File-rename atomicity

This is the most interesting design decision. Instead of a database table to track processed files, the Builder uses atomic rename() calls:

pull-{id}.txt               → ready to process
processing_pull-{id}.txt    → currently vectorizing
ragged_pull-{id}.txt        → vectorized successfully

public function build(): void
{
    $this->store->setup(); // ManagedStoreInterface

    $this->recoverOrphanedProcessingFiles();

    foreach (scandir($this->datasetDirectory) as $file) {
        if ('.' === $file || '..' === $file
            || str_starts_with($file, self::RAGGED_PREFIX)
            || str_starts_with($file, self::PROCESSING_PREFIX)) {
            continue;
        }
        if (!rename($this->datasetDirectory.'/'.$file, $this->datasetDirectory.'/'.('processing_'.$file))) {
            continue; // another process claimed it
        }

        try {
            $content = file_get_contents($this->datasetDirectory.'/processing_'.$file);
            $vector = $this->vectorizer->vectorize($content);
            if (768 !== \count($vector->getData())) {
                throw new \RuntimeException('Wrong dimensions');
            }

            $this->store->add(new VectorDocument(
                id: (int) preg_replace('/[^0-9]/', '', $file),
                vector: $vector,
                metadata: new Metadata(['content' => $content]),
            ));

            rename($this->datasetDirectory.'/processing_'.$file, $this->datasetDirectory.'/ragged_'.$file);
        } catch (\Throwable $e) {
            rename($this->datasetDirectory.'/processing_'.$file, $this->datasetDirectory.'/'.$file); // rollback
        }
    }
}

Crash-safe by design: if the script dies mid-way, recoverOrphanedProcessingFiles() re-queues orphaned processing_* files on the next run. No locks, no database, no race conditions.

Yes, the code shows that, despite what I said above:

As a result, only one vectorization at a time is possible.

Yes, I still tried 🤣.

Usage

The CLI exposes two commands:

# Full pipeline: fetch → dataset → vectorize
php bin/console mcp:build

# Re-vectorize without re-fetching
php bin/console mcp:build --skip-generation

# Re-fetch without re-vectorizing
php bin/console mcp:build --skip-build

The MCP server

For the LLM to have access to these freshly indexed reviews and run its searches by itself, you have to give it access.
Everything happens through the MCP protocol following this simplified call pipeline:

flowchart TD
    H["MCP Tool Call (review_as_group/person)"] --> I["Retriever (semantic search)"]
    I --> G["Qdrant (collection: reviews)"]
    I --> J["LLM Client (Claude Desktop)"]

The generation pipeline (fetch → dataset → vectorize) and the serving pipeline (retrieve → respond) share a single point in common: the Qdrant collection.

The MCP server exposes two tools and four prompts:

Tool	Role
`review_as_group`	Search by affiliation group (MEMBER, CONTRIBUTOR, NONE)
`review_as_person`	Search by a specific reviewer (nicolas-grekas, stof, etc.)

Prompt	Role
`review_as_group`	Formatted message using `review_as_group`
`review_as_person`	Formatted message using `review_as_person`
`get_stofed`	Forces the reviewer to "stof" — the most prolific reviewer of Symfony Core
`hq_review`	Multi-review: queries 14 reviewers and synthesizes a markdown report

Retrieval: MCP Tools

When a user sends a query through an MCP tool, here is what happens:

The tool builds a query combining reviewer, file path, and diff
RetrieverInterface::retrieve() vectorizes the query via Ollama
A cosine similarity search runs on Qdrant
The matching VectorDocument objects are returned
Their metadata['content'] is extracted and assembled into context

sequenceDiagram
    participant Client as Claude Desktop
    participant MCP as MCP Server (stdio)
    participant Tool as review_as_person
    participant Retriever
    participant Ollama
    participant Qdrant

    Client->>MCP: call_tool(review_as_person)
    MCP->>Tool: __invoke(pseudonym, file, diff, limit)
    Tool->>Retriever: retrieve(query, ['limit' => limit])
    Retriever->>Ollama: vectorize(query)
    Ollama-->>Retriever: query vector
    Retriever->>Qdrant: cosine similarity search
    Qdrant-->>Retriever: closest documents
    Retriever-->>Tool: VectorDocument[]
    Tool-->>MCP: found reviews (text)
    MCP-->>Client: tool result

#[McpTool(
    name: self::NAME,
    description: 'Tool retrieving a `limit` amount of reviews from `pseudonym` github user based on a given git a complete `file` path and `diff`. Results are separated by `\n\n---\n\n`.',
    annotations: new ToolAnnotations('Review matching file diff as github user', true, false, true, false)
)]
final readonly class ReviewAsPersonMatchingFileDiffTool
{
    public const string NAME = 'review_as_person';

    public function __invoke(string $pseudonym, string $file, string $diff, int $limit): string
    {
        $query = <<<TXT
        reviewer: $pseudonym
        file: $file
        diff:
        {$diff}
        TXT;

        try {
            $retrieved = $this->retriever->retrieve($query, ['limit' => $limit]);

            $return = [];
            foreach ($retrieved as $document) {
                $content = $document->getMetadata()['content'] ?? null;
                if (null === $content || !\is_string($content)) {
                    continue;
                }
                $return[] = $content;
            }
        } catch (\Throwable $exception) {
            return 'Error retrieving reviews: '.$exception->getMessage();
        }

        if (0 === \count($return)) {
            return 'No reviews found.';
        }

        return implode("\n\n---\n\n", $return);
    }
}

The HQ Review prompt

The hq_review prompt is the showcase feature. It queries 14 top-tier Symfony reviewers (GromNaN, dunglas, welcoMattic, nicolas-grekas, chalasr, stof, yceruto, mtarld, OskarStark, xabbuh, lyrixx, kbond, jderusse, alexandre-daubois), collects their historical feedback on the same file/diff, and asks the LLM to synthesize a markdown report with feedback weighted per reviewer.

The result is a code review that reads like a mini-symposium of Symfony Core maintainers — without requiring their time.

Usage

docker build -t symfony-reviewer-mcp-cli /path/to/Dockerfile
docker run -i --rm --add-host=host.docker.internal:host-gateway -e QDRANT_DSN=http://host.docker.internal:6333 -e OLLAMA_DSN=http://host.docker.internal:11434 symfony-reviewer-mcp-cli

Then configure Claude Desktop (or any MCP client) by adding the server to claude_desktop_config.json:

{
  "mcpServers": {
    "symfony-reviewer": {
      "command": "docker",
      "args": [
            "run", "-i", "--rm",
            "--add-host=host.docker.internal:host-gateway",
            "-e", "QDRANT_DSN=http://host.docker.internal:6333",
            "-e", "OLLAMA_DSN=http://host.docker.internal:11434",
            "symfony-reviewer-mcp-cli"
        ]
    }
  }
}

Environment variables

All the configuration goes through .env variables:

Variable	Role
`GITHUB_TOKEN`	GitHub personal access token
`QDRANT_DSN`	Qdrant service URL
`OLLAMA_DSN`	Ollama service URL
`BLACKLISTED_PATTERN`	JSON array of URL patterns to exclude from the cache
`APP_VERSION`	Version displayed in the MCP metadata

Lessons learned

This project taught me how the MCP protocol works, what a vector database is and how to use it. The architecture presented here is fairly standard for a RAG pipeline, but it was built with Symfony and can serve as a base for other experiments or use cases.

What worked well

File-rename atomicity: This pattern is elegant, crash-safe, and requires no infrastructure. Every PHP developer understands rename(). No Redis locks, no database migrations.
Incremental pipeline: Re-running mcp:build with existing files is a no-op. Iteration is fast — you can tweak the vectorization and only process new files.
PHP 8.x features: Constructor promotion, readonly properties, the pipe operator (|>), and invokable commands make the code significantly cleaner.
Ollama locally: embeddinggemma-300m runs on CPU without issues. 768 dimensions is modest enough for fast queries but rich enough for semantic search over code reviews.

What needs improvement

Had I had a more powerful machine with a dedicated GPU or unified memory (👋 Mac owners), I might have been able to change the following:

Naive Qdrant interaction: Documents are added one at a time. A batch upsert would be significantly faster for large volumes.
No incremental RAG updates: The pipeline is add-only. There's no "builtin" mechanism (it's possible via the Qdrant dashboard) to purge or update existing vectors when PR comments are edited on GitHub. Which is a real/false problem in itself, since you rarely find new comments on already-merged pull requests.
Add your own conventions: I added Symfony's reviews, but you too can modify and adapt the code to rely on an additional data corpus, like your colleagues' reviews.

What I'd do differently

Batch vectorization: Group documents and vectorize in batches for higher throughput
Async fetching: The data fetching phase is sequential per PR. Concurrent requests would significantly cut the initial build time.
GitHub webhook: Instead of periodically rebuilding, listen for merged PR events and update the dataset incrementally
Embedding model evaluation: 768 dimensions works well, but I should compare different models: smaller ones (like all-MiniLM-L6-v2, 384 dimensions) to improve performance, or much larger ones to assess the potential gain in search quality.
Wider context: PR comments and full diff: the current dataset only keeps review comments attached to a specific diff. It ignores general PR comments (issue comments, description) and above all the PR's full diff — a reviewer never judges an isolated line, they judge it in the context of the whole change. Injecting both would give the model far more material to understand why a review was worded the way it was.
Exploit the metadata field for GitHub's raw JSON: symfony/ai-store attaches a Metadata object (Symfony\AI\Store\Document\Metadata) to every VectorDocument, which travels all the way to the chosen store. With Qdrant, this Metadata maps exactly to the notion of payload: an arbitrary JSON object attached to each point, natively indexable and filterable — for example filtering by reviewer_association, by date, or by reaction count, without re-parsing the dataset text. Today, only content (the assembled dataset file text) is stored there; I would have added GitHub's raw API response (PR + review + reactions), to keep an exploitable trace independent of the generated text format.
Exploit the GitHub JSON reactions: Reactions would actually lend themselves to more than a simple filter: they could weight the search score itself, not just be returned in the content. Since version 1.14, Qdrant offers a Formula Query that lets you compose a final score from the initial similarity score and payload fields, in a single re-ranking formula. A review with ten +1 would then rank above an isolated review with zero reactions, at equal vector similarity — a way to surface the opinions the community itself validated. A feature worth exploring.

Does it work?

The big question: "are the reviews produced actually better?".

Answering Yes would be partially wrong. Indeed, today my evaluation remains essentially based on a general feeling rather than on real, tangible, quantifiable data.
The generated answers seem to me far more in the tone of a review that would have been made on Symfony's GitHub repository, and therefore closer to its conventions, than the answers obtained with a context-free LLM.
Finally, since an LLM is "probabilistic" by nature, I don't believe it's relevant to assert, based on my own observations and personal feeling alone, that the functioning of a tool is established.

Here is a example of a review done on that project to give you an idea :

---

### 1. fabpot
**Files:** `src/HTTP/CachedHttpClient.php`, `src/HTTP/CachedResponse.php`

> Thanks for the PR! A few things before we can merge:
>
> * Why is the cache key based on the URL only? For `POST` requests the body matters, otherwise all `/api/embed` calls will return the same result. This is a real bug, not an optimization issue.
> * Please add a test covering the "non-buffered" response case — `getContent()` then `toArray()` will fail on `EventSourceHttpClient` responses.
> * Do we need a `CHANGELOG` entry for the `CachedHttpClient`? I think we can keep it internal.
>
> Otherwise the approach is clean. Once the cache key is fixed, we can squash the commits.

---

### 2. nicolas-grekas
**Files:** `src/HTTP/CachedResponse.php`, `src/Kernel.php`

> Reading the response body twice is going to blow up the moment the response is not buffered. `toArray()` internally calls `getContent()` — so snapshot the content once and `json_decode` it, don't call both.
>
> Also, the decorated chain is wrong: `service(LoggedHttpClient::class)` no longer resolves to the logger once you decorate it with `CachedHttpClient`. Qdrant and Ollama are being routed through the GitHub cache without intent. Decorate a dedicated alias, e.g. `cached.github.http_client`, and keep `HttpClientInterface` as the plain chain.
>
> One more: `getContent(false)` is being snapshotted eagerly in the constructor — that defeats lazy streaming for large GitHub responses. Buffer lazily.

---

### 3. stof
**Files:** `src/Kernel.php`

> Service wiring nit: decoration replaces the decorated id, so `$httpClient => service(LoggedHttpClient::class)` gives you the `CachedHttpClient`, not the logging client. That's a scope leak — the Qdrant store is now coupled to a cache tuned for the GitHub API (see `BLACKLISTED_PATTERN`).
>
> I'd define a dedicated `logged.http_client` service for the store/platform and only decorate `cached.github.http_client` for the GitHub fetchers. Also check the `->decorate(..., priority: 1)` priorities — with equal priorities the order of application is by declaration order, which is fragile to read.
>
> And the `json:BLACKLISTED_PATTERN` env var — document its format in the README.

---

### 4. weaverryan
**Files:** `src/MCP/Tools/ReviewAsPersonMatchingFileDiffTool.php`

> Hey! Love the ergonomics of this tool — the `review_as_person` name makes the intent super clear. Great job composing the query with the pseudonym, file, and diff.
>
> One DX thought: when no reviews are found we return `No reviews found.` — that's good. But maybe give the caller a hint that they can reduce `limit` or widen the diff? Small thing, ignore if you want.
>
> Also, the metadata `content` check with the warning log is nice defensive coding. Keep it up! 🎉

---

### 5. derrabus
**Files:** `src/HTTP/CachedHttpClient.php`

> Two things:
>
> 1. `$key = md5($method.$url)` — please include the serialized options/body. Hash collisions here are silent correctness bugs, not just perf issues.
> 2. The `preg_match` on a compiled regex built via pipe chains is clever but hard to read. Since the blacklist is a list of exact strings, why not use `in_array` or a simple `str_starts_with` on the pattern list? Keep it simple.
>
> Also, the code is `final readonly` — good. But it implements `ResetInterface`; make sure the decorated inner `reset()` is reachable in `withOptions()` clones (it is, since you forward to the scoped client — just double-check the cache/lifecycle after cloning).

---

### 6. xabbuh
**Files:** `src/HTTP/CachedResponse.php`

> I have concerns about the snapshot in the constructor:
>
> * Calling `$response->getContent()` eagerly downloads and stores the whole payload. For the GitHub fetchers this is fine, but a general-purpose cache should stream lazily.
> * More importantly, `getContent()` followed by `toArray()` breaks for responses that disabled buffering (the Ollama `EventSourceHttpClient` forces `buffer => false`). This is an exploitable/observable crash — at minimum it should throw a clear `TransportException` or read once.
> * `getInfo()` filtering out closures is a nice touch, but the returned array is shallow — nested closures could still leak. Use a recursive filter or `json_encode/decode` the info array.

---

### 7. Tobion
**Files:** `src/HTTP/CachedHttpClient.php`

> The pipeline operator chains in `request()` are over-engineered for building a regex. `implode('|', array_map(preg_quote(...), $this->blacklistedPatterns))` is enough. As written, an empty blacklist produces the pattern `#^$#` which would match an empty call string — harmless, but misleading.
>
> More importantly: cache invalidation. There is none — responses are cached for a year (`defaultLifetime`). GitHub data changes; the fetchers need a way to bust the cache (e.g. include a version/tag in the key or a TTL per-URL). Otherwise reviews fetched once are served stale forever.

---

### 8. mpdude
**Files:** `src/RAG/Builder.php` (via `Store`)

> The Qdrant indexing loop swallows exceptions and logs `Index failed` — but the build then *continues* (I saw `Indexing document continues`). If a document fails vectorization, subsequent documents are still sent. That means the collection is only partially populated, and `review_as_person` will silently return "No reviews found" or partial results.
>
> Please make the build fail-fast or at least surface a summary count at the end ("indexed X / failed Y") so operators know the dataset is incomplete. Right now nothing tells us that only ~1106 of 8691 documents made it in.

---

### 9. WouterJ
**Files:** `src/Kernel.php`

> The container config reads really well — the decoration chain is easy to follow. Nice use of `env('json:BLACKLISTED_PATTERN')` and `StoreFactory::create(...)`.
>
> Minor: the `logged.http_client` vs `cached.github.http_client` distinction is muddied because both decorators use `priority: 1` and decorate each other's ids. I'd give them explicit service aliases (`github.logged.http_client`, etc.) so the intent is obvious. Also the unused `'stream_handler'` monolog handler and the commented-out `http` transport block could be cleaned up before merge.

---

### 10. alexislefebvre
**Files:** `tests/HTTP/CachedHttpClientTest.php`

> Nice test coverage — you test blacklist skipping, persistence across instances, `withOptions` cloning, and `reset`. 👍
>
> Missing cases I'd love to see:
>
> 1. A `POST` request with a body — assert that different bodies don't collide in the cache (this would catch the `md5(method.url)` bug).
> 2. A non-buffered/streaming response (`MockResponse` with `buffer => false` is hard to fake; but at least an SSE-like response) going through `CachedResponse` without throwing.
> 3. The cache should not be hit for `POST`/`PUT` (or should include the body in the key) — please encode that expectation in a test.

---

### 11. Nyholm
**Files:** `src/HTTP/LoggedHttpClient.php`, `src/HTTP/CachedHttpClient.php`

> As the http-client component maintainer: don't re-implement caching. Symfony's `HttpClient` supports a `cache` option natively via the `http_cache` from the contracts, and it handles cache keys, headers, `Vary`, and ETags properly. Rolling your own `md5(method.url)` cache key is a regression waiting to happen (it already broke on POST bodies).
>
> If you keep the custom decorator, at least delegate to `CacheItemPoolInterface` semantics and include the request payload + relevant headers in the key. And please make `stream()` forward correctly — it does, but note that cached responses can never stream, which may surprise callers.
>
> Also: `FileSystemAdapter` on a single Docker container is fine, but for multi-instance deploys you'll want a shared pool (Redis). Worth a comment.

---

### 12. jderusse
**Files:** `src/RAG/Builder.php`, `src/HTTP/CachedHttpClient.php`

> The elephant in the room: the per-document vectorization loop is serial. 8691 documents, ~10s each — that's ~24h to build the RAG, and with the cache bug most embeddings were identical (same URL → same key). That's why retrieval feels broken.
>
> Fixes I'd push for:
> * Parallelize vectorization with Symfony's `AsyncResponse` / `stream()` over batches.
> * Include the body in the cache key (obviously).
> * Index the docs that failed (`Index failed` ×636) with retry/backoff.
>
> Also `Builder` should checkpoint progress so a crash doesn't restart from zero.

---

### 13. chalasr
**Files:** `src/MCP/Tools/ReviewAsPersonMatchingFileDiffTool.php`, `src/Command/ServeCommand.php`

> Tool ergonomics are good — `limit` is explicit, errors are caught and surfaced. But: the error path returns `Error retrieving reviews: {message}` as a *successful* tool result. For an MCP server, real failures should be proper exceptions/tool errors, not strings, otherwise the client can't distinguish "no data" from "server broken".
>
> Also, the query string embeds the raw diff with no size guard — a huge diff will blow the embedding context window. Truncate or chunk the diff.
>
> And the serve command: make sure `APP_DEBUG` is off in prod and there's a graceful shutdown on SIGTERM.

---

### 14. yceruto
**Files:** `src/Kernel.php`, `src/HTTP/CachedHttpClient.php`

> The routing of the HTTP decorators deserves attention: `LoggedHttpClient::class` is decorated by `CachedHttpClient`, so every consumer referencing it — including the Qdrant store — ends up behind the GitHub cache. That coupling is accidental.
>
> I'd restructure like this:
> ```


> HttpClientInterface          # plain
>  └─ logged.http_client       # logging only (for Qdrant/Ollama)
>  └─ cached.github.http_client # cache + github token (for GitHub fetchers)
>

Two separate chains, no cross-decorating. Then the cache key issue (URL-only, no body) also only affects GitHub GETs, which is safe.

After that, the 14 review_as_person calls will stop returning the buffering is disabled error and start returning real reviews.




## To conclude

<div style="width:100%;height:0;padding-bottom:56%;position:relative;">
    <iframe src="https://giphy.com/embed/NRiRXQTwbijNba2l2l" width="100%" height="100%" style="position:absolute" frameBorder="0" class="giphy-embed" allowFullScreen></iframe>
</div>

<p><a href="https://giphy.com/gifs/The-Animal-Crackers-Movie-baking-try-it-NRiRXQTwbijNba2l2l">via GIPHY</a></p>

Try it yourself — the [project](https://github.com/ktherage/symfony-review-mcp) is designed to be self-contained and independent. The data is publicly accessible, and you can spin up a Qdrant and Ollama instance easily with [Docker](https://www.docker.com/).

To install it:



```bash
git clone https://github.com/ktherage/symfony-review-mcp
cd symfony-review-mcp
docker compose run --rm cli composer install
docker compose run --rm cli bin/console mcp:build
docker compose up -d

The most surprising thing I learned building this project: PHP is a perfectly viable language for RAG pipelines. Symfony's HttpClient, Cache, and Console components, combined with the symfony/ai-* packages, handle everything from HTTP decoration to vector database operations.

You don't need Python to do semantic search.

Sometimes the best tool for the job is the one you already master.

API Platform Con 2025 - Day 2

Thérage Kévin — Wed, 24 Sep 2025 08:00:19 +0000

I had the opportunity to attend the API Platform Con 2025 thanks to SensioLabs and here is what I learned through the talks I viewed.

How LLMs are changing the way we should build APIs (Fabien Potentier)

Slides of this talk are available : https://speakerdeck.com/fabpot/how-ai-agents-are-changing-the-way-we-should-build-apis

Fabien Potentier shared insights about how Large Language Models are fundamentally changing the way we need to think about API design. As he mentioned, this is a world that changes so fast that some assertions might already be outdated.

Agents ?

LLMs are evolving beyond simple text generation into autonomous agents. According to Anthropic's definition, an agent is an LLM using tools in a loop. These LLMs are self-directed - they can reason about things, they can plan, and have memory.

An AI agent is kind of a mix between a machine and a human, combining the computational power of machines with human-like reasoning capabilities.

Who can consume your app ?

Back in the days, the consumers were clearly defined:

Website:

Human users only

CLI tools:

Only for developers

API:

Only for machines
Semi-private (to decouple frontend) or public

Nowadays, APIs are mostly used to expose data, but AI agents have changed the game completely. They are able to interact with all three interfaces:

Websites can be scraped by AI - agents can navigate and extract information from web interfaces
CLI tools can be used through MCP servers - providing structured tool access
APIs - LLMs (e.g., in chatbots) are often wrappers on top of APIs. Furthermore, LLMs can also write API calls directly.

But all three have different expectations, and this creates new challenges.

The Challenge: APIs for Humans vs. Machines vs. AI Agents

APIs are optimized for machines, but when something breaks, you need a human in the loop. However, AI agents are autonomous but, like humans, they need help and guidance.

Take HTTP status codes as an example. They provide information about problems, but AI agents need more context.
HTTP responses can provide context about errors, but responses provided by APIs might not be up-to-date or accurate, causing LLMs to get stuck.

Here is a common workflow pattern followed by LLM : Thought → Action → Observation.
Without guidance provided via prompts, it can loop over the same problem, encountering the same Observation after performing the same Action—potentially forever.
LLMs will try to guess and self-correct, which is probably bad for two reasons:

Costly - more API calls and processing
Time loss - inefficient problem resolution
Resource greedy - GPU time and electricity are consumed without solving the problem

Tip: The fewer round trips you have with an LLM, the more "deterministic" it becomes, even though LLMs are inherently not deterministic.

Best Practices for LLM-Friendly APIs

Everything that is valid for LLMs is also valid for humans.

Error Messages

Be precise with your error messages: "Bad date format. Use 'YYYY-MM-DD'."
Benefits:

Fewer tokens consumed
Smaller context window usage
Faster resolution

Consistent Naming

Use the same naming pattern everywhere. For example, use user_id consistently across all endpoints.
Benefits:

Predictable patterns
LLMs like consistency
Easier to understand and use

Documentation

Fix examples and remove outdated content
Fewer problems and hallucinations
Consider using llms.txt files - documentation specifically formatted for LLMs in Markdown

Performance Considerations

AI agents are slow, so reducing the number of requests provides a significant performance boost.

Intent-First API Design

Design your APIs to capture and preserve user intent rather than just exposing CRUD operations.

Testing Challenges

Testing AI agents is super difficult because:

LLMs are not deterministic
You need to set temperature to 0 for more consistent results
Use concise prompts
Ultimately, you need a human to judge the quality of actions performed by the LLM, making automated testing complex

Technical Considerations

Tokens vs. Text

Understanding tokenization is crucial. Tools like tiktokenizer.vercel.app help visualize how text is tokenized:

Language matters: English costs less in tokens than French or Japanese for example
Unique IDs are problematic: UUIDs are bad for tokenizers, ULIDs are better
Shorter is not always better in terms of token efficiency
Date formats matter for token consumption
JSON is not the best format for LLMs - Markdown is better and uses fewer tokens

More tokens require more money and create larger context windows, which negatively impact AI agent response times and relevance.

Security and Credentials

AI agents are bad at dealing with credentials. The solution is to use MCP (Model Context Protocol) servers that:

Handle credentials securely
Provide tools to AI agents
Give limited scope permissions to MCP actions
Act as a secure intermediary between the LLM and your APIs

Log Everything

Given the complexity and unpredictability of AI agent interactions, comprehensive logging becomes essential for debugging and improving the system.

The New Experience: AX (AI Experience)

Fabien introduced the concept of AX (AI Experience) alongside the familiar UX (User Experience) and DX (Developer Experience). This represents a new dimension of API design focused on how well your API works with AI agents.

Key aspects of good AX include:

Up-to-date documentation and examples (avoiding outdated examples that could mislead the LLM)
Using llms.txt files with all useful documentation for the LLM in Markdown format
Clear, consistent error messages
Intent-preserving API design
Efficient token usage

The fascinating aspect is that many improvements for AX also benefit traditional DX, making APIs better for both human developers and AI agents.

Build a decoupled application with API Platform and Vue.js (Nathan de Pachtere)

Nathan de Pachtere shared his experience building decoupled applications using API Platform for the backend and Vue.js for the frontend. His insights covered the differences between headless and decoupled approaches, practical implementation strategies, and the benefits of monorepo architecture.

Headless

Headless architecture involves creating a business-focused API that anyone can use independently. Think of the GitHub API - it's designed as a standalone service that provides all the functionality needed to interact with GitHub's features, completely independent of any specific frontend implementation.

The goal is to create business logic and provide an API that everyone can utilize for their own purposes.

Decoupled

Decoupled architecture is similar but more focused. You provide a frontend that relies specifically on your API, creating what's essentially a backend-for-frontend pattern. The API doesn't seem to be made for independent use outside of the specific application - it's tailored to serve the frontend's exact needs.

Why Choose This Approach?

Advantages

Separation of responsibilities - Clear boundaries between frontend and backend concerns
Team management - Enables specialist teams to work independently on their expertise areas
Capitalization - Reusable components and logic across different projects
Future-proofing - AI might be the interface used in the future, making an API-first approach valuable

Disadvantages

Complexity - More complex setup for existing projects that need to be refactored

Headless Implementation

using API Platform

The process follows a business-driven approach:

Represent the API based on business needs - Focus on what the business actually does
Translate into entities and workflows - Convert business processes into technical implementations
Write only the necessary code - Keep it simple initially
Then optimize and refactor - Improve performance and code quality
Iterate - Continuously improve based on feedback
Go beyond CRUD - Implement meaningful business operations, not just basic data manipulation

Providing API Keys

For machine-to-machine authentication:

Create a simple interface for creating/deleting configurable keys with specific permissions
Consider external identity providers like Keycloak or Zitadel for more advanced use cases
Important principle: Don't mix human users with machine users - they have different needs and security requirements

Nathan emphasized making tests simple and easy to implement, integrating them naturally into the development workflow rather than treating them as an afterthought.

Deprecation Strategy

When evolving your API:

Deprecate endpoints, resources, and properties gradually
Give consumers time to adapt to changes
Communicate changes clearly before removing functionality

This approach maintains backward compatibility while allowing the API to evolve.

Decoupled Implementation

using Vue.js

Nathan chose Vue.js for several reasons:

Independent and community-driven - Not controlled by a single corporation
Composition API (Vue 3) - Promotes code reusability and better organization
Excellent Developer Experience - Great tooling and development workflow
Top performance - Fast and efficient (until the next framework comes along, as he joked)

API Connection

For connecting the Vue.js frontend to the API Platform backend:

Code Generation

Use openapi-ts.dev to generate TypeScript types and composables from your OpenAPI specification. This ensures type safety and reduces manual work.

Important principle: Don't use the generated types directly as base objects in your frontend. Create your own models to maintain proper decoupling between frontend and backend representations.

HTTP Client and State Management

Tanstack Query - For efficient data fetching and caching
TypeScript throughout - Ensures type safety across the application
VS Code for Vue.js development - Better integration compared to JetBrains IDEs for Vue.js work

High-Level SDKs

Provide high-level SDKs to facilitate API integration, making it easier for developers to work with your API.

Version Management

Polyrepo vs Monorepo

Monorepo doesn't mean monolith - this is a crucial distinction:

Monorepo = Multiple separate projects in a single repository
Monolith = Single application handling everything

Monorepo Benefits

The goal is to simplify the workflow:

Unified way of thinking about code - Consistent patterns across projects
Consistency - Shared tooling and configurations
Facilitates sharing - Easy code and component reuse
More efficient teamwork - Simplified collaboration and dependency management

Tooling

Nathan recommended moonrepo.dev as an open-source tool for managing monorepos. You can find more information at monorepo.tools.

Real-World Example

Nathan shared their experience with enormous benefits:

Code generalization - Reusable patterns and components
Functionality sharing - Common libraries across projects
Technology-based organization - Projects use shared libraries organized by technology stack

You can see a practical example of this approach in the Lychen project (lychen.fr), which demonstrates a well-structured monorepo with clear separation between backend, frontend, and shared tools.

The Lychen project shows how to organize a monorepo with:

Backend (API Platform/PHP)
Frontend (Vue.js/TypeScript)
Shared tooling (Moonrepo, Docker, testing tools)
Clear technology boundaries while maintaining efficient code sharing

Jean-Beru presents: Fun with flags (Hubert Lenoir)

Slides of this talk are available : https://jean-beru.github.io/2025_09_apiplatformcon_fun_with_flags

Jean-Beru (Hubert Lenoir) presented the fascinating world of feature flags and their practical implementation. As Uncle Ben said in Spider-Man: "With great power comes great responsibility" - and feature flags are indeed a powerful tool that requires careful consideration.

What are Feature Flags?

Feature flags (also known as feature flipping or feature toggles) are a software development technique that allows you to turn features on or off without deploying new code. They act as conditional statements in your code that determine whether a particular feature should be enabled or disabled for specific users, environments, or conditions.

Types of Feature Flags

Release Flags

Mainly used to test new features in production environments safely.

Continuous development - Even if a feature is not ready, you can continue developing and deploying (not ready = disabled)
Safe deployment - Deploy code with features turned off, then enable them when ready
Gradual rollout - Enable features for small groups before full release

Experiment Flags

Used to compare different versions of your application.

A/B testing - Compare different implementations or user experiences
Must be followed by metrics - Track performance and user behavior
Partial enablement - Enable for specific percentages (e.g., 20% of users)

This approach allows data-driven decisions about which features or implementations work best for your users.

Permission Flags

Control access to features based on user permissions or subscription levels.

Blocking access based on permissions - For example, paid features only available to premium subscribers
Role-based feature access - Different features for different user types
Subscription tiers - Enable advanced features for higher-tier customers

Operational Flags

Security belt and kill switch functionality.

Allow disabling cumbersome features - Quickly turn off resource-intensive features during high load
Emergency response - Disable problematic features without deployment
Performance management - Control system load by toggling expensive operations

For more detailed information about feature flag patterns, Martin Fowler has an excellent article at https://martinfowler.com/articles/feature-toggles.html.

Implementation

There are many feature flag providers available in the market, but the implementation doesn't necessarily need to use Symfony's Security component.

Why Not Security Component?

Restricted to current user context - Limitations when flags need to work across different user contexts
Authentication timing issues - Authentication happens after routing, which can lead to unwanted forbidden error codes
Flexibility needs - Custom implementations can better integrate with existing providers like Unleash

Requirements for a Good Implementation

A solid feature flag system should provide:

Simplicity - Easy to implement and use
Integrated debugging - Clear visibility into which flags are active
Multiple sources - Ability to switch between different flag providers
Various provider support - Work with different feature flag services
Cacheable - Performance optimization through caching mechanisms

Symfony Integration

There's a work-in-progress FeatureFlag component for Symfony (PR #53213). This component aims to provide native support for feature flags within the Symfony ecosystem.

With API Platform

Feature flags can be easily tested via a separated bundle: ajgarlag/feature-flag-bundle.

Implementation Steps

Decoration of API Platform provider - Use the decorator pattern to wrap existing providers with feature flag logic
Use FeatureFlag WIP component interface - Integrate with the upcoming Symfony FeatureFlag component

Example with GitLab Provider

GitLab provides a feature flag service that uses Unleash in the background. This integration allows you to:

Manage flags through GitLab UI - Familiar interface for teams already using GitLab
Leverage Unleash capabilities - Powerful feature flag engine under the hood
Integrate with CI/CD pipelines - Automatic flag management as part of deployment process

Profiler Integration

The implementation includes Symfony Profiler integration, providing:

Debug information - See which flags are active during development
Performance insights - Monitor the impact of feature flag checks
Development workflow - Easy testing and debugging of flag behavior

Advantages

Implementing feature flags brings several significant benefits:

Deploy Continuously

Decouple deployment from release - Deploy code safely with features disabled
Reduce deployment risk - Lower chance of breaking production
Faster iteration cycles - More frequent, smaller deployments

Progressive Testing

A/B testing capabilities - Compare different approaches with real users
Gradual rollouts - Start with small user groups and expand
Data-driven decisions - Make choices based on actual usage metrics

Quick Turn Off

No redeployment needed - Instantly disable problematic features
Emergency response - Rapid reaction to production issues
Business continuity - Keep core functionality working while fixing problems

Separate Code from Feature Release

Independent timelines - Development and business release schedules can differ
Marketing coordination - Align feature releases with marketing campaigns
Stakeholder management - Give business teams control over when features go live

Feature flags represent a powerful paradigm shift in how we think about software deployment and release management, enabling more flexible, safer, and data-driven development practices.

PIE : The next Big Thing (Alexandre Daubois)

Extensions ?

Extensions are like composer packages, but written in C, C++, Rust, and now Go.

They live at a lower level, which makes them much faster than pure PHP code.

Frameworks like Phalcon are themselves shipped as extensions.

Installing a third-party lib

Traditionally, installing an extension is much more painful than a composer install.

It usually involves:

Downloading the source code.
Compiling it with phpize and make.
Adding a line to php.ini to enable it.
Restarting PHP-FPM or Apache to load it.

This workflow makes extensions harder to distribute and standardize compared to Composer packages.

PECL

Clunky and outdated.
Slow to install.
Lacks proper security (no package signing).
Not officially backed by PHP, and some in the community want to phase it out.

docker-php-extension-installer

A widely used community project that simplifies extension installation inside Docker images.

Instead of writing complex apt-get + phpize + make commands, you just add:

COPY --from=ghcr.io/mlocati/php-extension-installer /usr/bin/install-php-extensions /usr/local/bin/

RUN install-php-extensions xdebug redis

This is great, but still not perfect—it remains Docker-specific and doesn’t integrate with Composer or Packagist.

Project to replace PECL

The pie-design repository defines the foundations of PIE, a new way to install extensions as easily as PHP packages.

Started in March 2024.
Version 1 released in June 2025.
PIE is distributed as a single phar file: just download it and use it.
All extension metadata is stored in Packagist.

Command options

pie install ext-xdebug → installs an extension and updates php.ini.
pie uninstall ext-redis → removes an extension.
pie update → upgrades to the latest available version.
pie search redis → searches for extensions in Packagist.
Running pie without arguments reads extensions from composer.json and installs them.

Other features:

Add repositories via Composer, VCS, or local paths.
Automatic php.ini update.
Support for GH_TOKEN to install from private repositories.
OS compatibility restrictions.
Symfony CLI integration: symfony pie install.

The future of extensions

PIE is the theoretical replacement for PECL.

An RFC vote was held, closing on September 20, 2025.

Almost everyone voted yes, which means PIE is now the official successor to PECL.

Make your devs happy by normalizing your API errors (Clément Herreman)

Errors are not just bugs. They’re an opportunity to give users autonomy through clear feedback.

What is an error?

An error is any behavior—intentional or not—that prevents the user from completing their task.

Why normalize errors?

To react properly to a precise issue:
- Retrying a token.
- Handling distributed system failures.
- Fixing configuration issues.
To present errors consistently:
- Clear and understandable messages for end-users.
- Precise identification to ease support.
- Keeping some details vague for security reasons.

How?

Errors can be classified into three categories:

Errors that belong to your domain: you own them, so enrich them with context.
Errors that don’t belong to your domain but still happen: wrap them with a code and enrich them.
Rare/unexpected errors: keep the default JSON output.

RFC 7807: Problem Details for HTTP APIs

This RFC defines a standard JSON structure for errors:

type: unique machine-readable code.
title: short, human-readable summary.
detail: contextual explanation of this particular error.
instance: URL to the error catalog.
...: any custom fields you want.

Example HTTP response

HTTP/1.1 401 Unauthorized
Content-Type: application/problem+json

{
  "type": "https://example.com/errors/authentication_failed",
  "title": "Authentication failed",
  "detail": "Your token has expired. Please request a new one.",
  "instance": "/login"
}

API Platform

API Platform provides a ready-to-use ApiPlatform\Problem\Error class to implement RFC 7807.

Organizing errors

Keep only business exceptions in the domain layer.
Wrap infrastructure errors before sending them to the client.

Documenting errors

Errors can be declared as attributes on operations, making them explicit in the API docs.

Improvements: RFC 9457

RFC 9457 is essentially the same as RFC 7807, with some additions:

A registry of errors via schema.org.
A mechanism for returning multiple errors at once (though strongly discouraged).

As Clément highlighted: RFC 9457 doesn’t bring much practical value, and some of its suggestions are even discouraged in the spec.

Symfony and Dependency Injection: From past to future (Imen Ezzine)

Dependency Injection (DI) is the “D” in SOLID, and it has been a cornerstone of Symfony’s design for nearly two decades.

This talk explored its history, evolution, and what’s next.

The early days

2007 – Symfony 1

Services instantiated directly, often via sfContext() (a singleton).
Hard to test, rigid, tightly coupled.
No real container.

Symfony 2 and the paradigm shift

2011 – Symfony 2

Introduction of a central container.
Services configured via YAML and parameters.
Dependencies injected as constructor arguments.
Autowiring introduced in Symfony 2.8.

2015 – API Platform v1

Heavy reliance on autowiring (then experimental).

2016 – API Platform v2

@ApiResource annotation magic powered by the DI component.
Data persisters and providers had to be tagged manually.

2017 – Symfony 3.3 / API Platform 2.2

Autowiring + autoconfigure.
Manual tagging mostly eliminated (providers/persisters automatically wired).
Symfony 3.4: services private by default.

Symfony 5 to Symfony 7

2021 – Symfony 5.3

DI powered by attributes → much less YAML.
#[When] attribute for conditional services.

Symfony 6.0 – 6.3

New attributes for corner cases.
#[Autowire] attribute for precise service injection.
Support for env vars and parameters via attributes.
#[AsAlias] to alias services.

2022 – API Platform 3.0

New state processors and providers replace older persister/provider pattern.

2023 – Symfony 7

#[AutoconfigureTag] → automatic tagging (used in API Platform filters).
TaggedIterator → inject multiple tagged services.
AutowireIterator → autowire all classes implementing an interface.

Symfony 7.1 – 7.3

#[AutowireMethodOf] to autowire a single method.
#[WhenNot] for conditional services.
when parameter in #[AsAlias].

Takeaways

Over 20 years, DI in Symfony evolved from:

Manual instantiation →
Manual configuration →
Automatic configuration through attributes.

This journey has made Symfony projects more testable, maintainable, and developer-friendly while reducing boilerplate.

Credits

Cover image by Nicolas Detrez

API Platform Con 2025 - Day 1

Thérage Kévin — Wed, 24 Sep 2025 07:52:30 +0000

I had the opportunity to attend the API Platform Con 2025 thanks to SensioLabs and here is what I learned through the talks I viewed.

Enhance your API Platform APIs with Go thanks to FrankenPHP (Kévin Dunglas)

Slides of this talk are available : https://dunglas.dev/2025/09/the-best-of-both-worlds-go-powered-grpc-for-your-php-and-api-platform-apps/

API Platform is celebrating its 10th anniversary this year, having been created on January 20, 2015. Originally a Symfony bundle, it is now usable with Laravel or even without any framework. With over 14,000 stars on GitHub and 921 code and documentation contributors, API Platform has become an essential tool for creating APIs.

Kevin highlighted that it has also been the starting point for many related projects such as Mercure and FrankenPHP, and many Symfony components were first developed for API Platform.

He also paid tribute to Ryan Weaver, a key contributor, and encouraged attendees to support his family through the GoFundMe "In memory of Ryan Weaver: For his son Beckett".

One Model, Many API Architecture Types

With API Platform, you can use the same DTO, the same code, and the same PHP class to generate different output formats with just a few configuration changes.

Here are some of the supported formats:

Hydra
OpenAPI
HAL
JSON:API
GraphQL
Mercure (SSE support)

This approach eliminates code duplication across different API format requirements.

Why gRPC is missing in API Platform

Currently, gRPC is not supported by API Platform. Here's why:

gRPC does not follow REST principles.
It is different from GraphQL.
It uses Protobuf (a binary format) instead of JSON for the output format.

Most of the time, in classic gRPC architecture, PHP is not a candidate.

However, gRPC has several advantages:

Fast and efficient
Strongly typed
Language agnostic: a code generator allows generating data structures in many languages.

Use cases for gRPC include:

Microservices
Internet of Things (IoT)
Critical components where performance is essential

How gRPC Works

gRPC operates on HTTP/2 and uses Protocol Buffer .proto files to define service contracts. These definitions enable automatic code generation across multiple programming languages. The binary serialization format provides more efficient data transmission than JSON, while HTTP/2's multiplexing supports high-performance communication.

Moreover, the official gRPC documentation recommends using non-PHP languages for gRPC servers due to PHP-FPM's request lifecycle limitations.

gRPC with FrankenPHP

Thankfully, FrankenPHP offers a way to write extensions in Go that can be exposed in PHP, making it possible to use gRPC with API Platform. The FrankenPHP gRPC extension is available on GitHub and is testable. It uses the Go gRPC server and is designed to be used with or without API Platform.

For more information on configuration and usage of this extension, please refer to the GitHub repository documentation.

Testing can be done with gRPCui. It is important to note that this solution is still experimental.

Extend Caddy Web Server with Your Favorite Language (Sylvain Combraque)

Caddy is a modern, fast, and easy-to-use web server that simplifies the process of serving websites and web applications. It is known for its automatic HTTPS configuration and simple syntax. Matt Holt, the creator of Caddy, has made significant contributions to the web server landscape with Caddy's unique features and ease of use.

Extending Caddy

Using xcaddy Build

Extending Caddy can be done using the xcaddy build tool, which allows you to customize and extend Caddy with plugins written in Go. This tool provides a straightforward way to add new functionalities to Caddy.

Using WebUI from Caddy Website

Caddy also offers a WebUI that can be accessed from the Caddy website. This interface provides an easy way to manage and configure your Caddy web server.

Extending Caddy with Go

For more detailed information on how to extend Caddy with Go, you can refer to the official documentation.

Using Interpreter

While using interpreters to extend Caddy has its advantages, there are also some drawbacks:

You need one interpreter per language.
New versions of the language require new interpreters.
Each interpreter is maintained separately.
You may need to re-implement types.

WASM x WASI x darkweak/wazemmes for Caddy Extension in Any Language

WebAssembly (WASM) is a binary instruction format that promises to enable programs to run at near-native speed on the web. The promise of "build once, run everywhere" makes WASM an attractive option for extending Caddy. However, the current documentation is not user-friendly, and there are some bugs to be aware of.

WebAssembly System Interface (WASI) is a system interface designed to allow WebAssembly modules to interact with the operating system in a secure and portable way. This combination of WASM and WASI allows developers to write code in their preferred language and compile it to WASM for execution in a browser or server environment.

For more information on using WASM and WASI in Caddy, you can check out the darkweak/wazemmes repository on GitHub.

Mercure, SSE, API Platform and an LLM Elevate a Chat(bot) (Mathieu Santostefano)

Slides of this talk are available : https://welcomattic.github.io/slides-real-time-ai-chatbot-with-mercure/1

Origin of the Subject

The initial customer need was to create paid expert chat exchanges. The first version used an API + React, but lacked message history. Mercure was chosen for secure message distribution to customers via JWT.

Evolved needs:

Assist experts with an AI assistant
Allow AI to handle the first part of the conversation
Allow experts to take over when needed

Toolbox

Mercure - Real-time Exchanges

Architecture:

Server => Hub => Client
Client => Hub => Client

SSE

Server-Sent Events (SSE) is a technology that allows a server to send real-time updates to a client via a persistent HTTP connection. The client listens to a stream of events sent by the server.

API Platform

LLM

Data generation and intelligent responses

Symfony Messenger

Asynchronous process management

Symfony AI

Equivalent to Mailer/Notifier but for AI providers:

Platform: unified interface for all AI providers
Agent: agentic AI creation
Store: data storage abstraction
MCP SDK: now officially supported by Anthropic
AI Bundle: full integration with Symfony
MCP Bundle: additional components

Implementation

Technical flow:
User => message => Mercure (Storage) <= Symfony SSE client => Symfony Messenger => Mistral => Mercure => AI response => User

Secure private chat via JWT (JSON Web Tokens) - an open standard for securely exchanging data between parties.

Sending a message to Mercure

fetch(this.hubURL, {
    method: 'POST',
    credentials: 'include', // Send JWT cookie
    body: new URLSearchParams({
        topic: topic,
        data: JSON.stringify(
            new MercureUpdateData(
                conversationId,
                msg,
            ),
        ),
        private: 'on' // restrict message to subscribed clients
    })
});

Connecting to Mercure

const eventSource = new EventSource('/sse-endpoint');
eventSource.onmessage = (event) => {
  console.log('New event received: ', event.data);
};

Symfony SSE Client

Built-in EventSourceHttpClient:

use Symfony\Component\HttpClient\Chunk\ServerSentEvent;
use Symfony\Component\HttpClient\EventSourceHttpClient;
use Symfony\Component\HttpClient\HttpClient;

$eventSourceClient = new EventSourceHttpClient(HttpClient::create());

$connection = $eventSourceClient->connect("YOUR-MERCURE-URL");

while (true) {
    foreach ($eventSourceClient->stream($connection, 2) as $r => $chunk) {
        if ($chunk->isTimeout()) continue; // Keep the connection alive.
        if ($chunk->isLast()) return; // Connection closed by server.
        if ($chunk instanceof ServerSentEvent) $this->processSSE($chunk);
    }
}

Dispatching messages with Messenger

use Symfony\Component\HttpClient\Chunk\ServerSentEvent;

function processSSE(ServerSentEvent $event): void
{
    $data = $event->getArrayData();

    // do some checks before asking LLM
    if (!$this->shouldProcessWithAi($data)) {
        return;
    }

    // Dispacth message to ask LLM
    $this->messageBus->dispatch(
        new ProcessAiResponseMessage(
            conversationId: $data['conversationId'],
            userMessage: $data['message'],
            sseMessageId: $event->getId(),
            timestamp: $data['timestamp']
        ),
    );
}

Symfony AI Configuration

YAML configuration of AI bundle with Mistral

ai:
    platform:
        mistral:
            api_key: '%env(MISTRAL_API_KEY)%'

    agent:
        default:
            platform: 'symfony_ai.platform.mistral'
            model:
                class: 'Symfony\AI\Platform\Bridge\Mistral\Mistral'
                name: !php/const Symfony\AI\Platform\Bridge\Mistral\Mistral::MISTRAL_LARGE

Handler Example

// Symfony AI Bundle code example
use Symfony\AI\Agent\AgentInterface;
use Symfony\AI\Agent\Chat;
use Symfony\AI\Platform\Message\Message;
use Symfony\AI\Platform\Message\MessageBag;
use Symfony\AI\Store\StoreInterface;

class MessageHandler
{
    public function __construct(
        private readonly AgentInterface $agent,
        private readonly StoreInterface $messageStore,
    ) {
    }

    public function __invoke(ProcessAiResponseMessage $message)
    {
        $chat = new Chat($this->agent, $this->messageStore, "UNIQUE_ID_TO_PROMPT");
        $messages = $this->messageStore->load("UNIQUE_ID_TO_PROMPT");

        if ($messages->count() === 0) {
            // retrieve system prompt from somewhere ...

            // Programmatic System prompt injection
            $chat->initiate(new MessageBag(
                Message::forSystem("SYSTEM_PROMPT_INJECTION"),
            ));
        }

        $llmAnswer = $chat->submit(Message::ofUser($message->userMessage));

        // do something with the answer
    }
}

In his final words Mathieu dedicated his talk in memory of Ryan Weaver, whose contributions continue to inspire the Symfony community. He also thanked Christopher Hertel for the Symfony AI initiative.

How API Platform 4.2 is Redefining API Development (Antoine Bluchet)

Slides of this talk are available : https://soyuka.me/api-platform-4-2-redefining-api-development/

Looking back at version 4.0:

610 commits
~200,000 lines of code
291 issues opened
230 issues closed

What's New in 4.2

Key features of this release:

FrankenPHP integration
State Options
Query parameters enhancements
Performance improvements
Laravel compatibility
PHP File Metadata

Metadata Enhancements

Metadata from PHP Files

New metadata system allows extracting API configuration directly from PHP files. It is not documented yet (AFAIK) but you can see the related PR of Loïc Frémont https://github.com/api-platform/core/pull/7017.

Metadata Mutator

A new way to programmatically modify metadata:

More flexible configuration
Runtime adjustments
Cleaner architecture

From API Filter to Parameters

API Filter Retrospective

The #[ApiFilter] attribute was doing a lot of things in the background, such as:

Declare services with filter tags
Generate documentation
Apply database operations
Work with multiple properties

This was confusing and also not respecting Single Responsibility Principle. That's the reason why API Platform maintainers have decided to rework that to Parameters.

Filter Documentation Improvements

Now documentations are generated separately. This can be done with two new interfaces

JsonSchemaFilterInterface
OpenApiParameterFilter

Filtering System

Now Filter are independent through a new FilterInterface with:

Simplified apply() method
No constructor requirements
Dependency-free design

Parameter System

The #[ApiFilter] attribute will leave his place to a new property of Operations attributes called parameters

New Filter Types

Free text search capabilities
URI variable provider

JSON Schema Enhancements

Some improvements were made on JSON Schema generation. Those changes could imply a backward compatibility break for tools using the former JSON Schema.

Improvements

Schema mutualization
30% smaller OpenAPI specification files
Reduced I/O operations

A new tool is now recommended : pb33f.io as it is more feature-rich and better maintained than Swagger UI.

Performance

Performance benchmarks comparing Nginx vs FrankenPHP:

More benchmarks available at soyuka.github.io/sylius-benchmarks/

JSON Streamer improvements:

~32.4% better request/second performance
Configurable via settings

State Options

New features for querying subresources:

More efficient data loading
Entity class magic (RIP Ryan)

Data Mapping

New mapping capabilities:

Database to API representation mapping
Symfony ObjectMapper integration
Better data transformation

Debugging

Profiling tools are back!

Backward Compatibility

Many new features added
No deprecations in this version
Parameters system is no longer experimental

Looking Ahead to API Platform 5.0

Planned changes:

#[ApiFilter] deprecation (migration script coming soon)
More JSON Streamer usage
Object Mapper feature requests
Community-driven improvements

Design pattern the treasure is in the vendor (Smaïne Milianni)

Slides of this talk are available : https://ismail1432.github.io/conferences/2025/apip_con/index.html

In this talk Smaïne made a tour on Design Pattern that are commonly used without any knowledge that they are in the vendors we use on a daily basis. He also showcased small and comprehensible code PHP snippets explaining some of them.

Among them were :

The Strategy Pattern
The Adapter Pattern
The Factory Pattern
The Builder Pattern
The Proxy Pattern
The Observer Pattern
The Event Dispatcher Pattern
The Decorator Pattern
The Facade Pattern
The Template Pattern
The Chain of Responsibility Pattern

Smaïne also ended with a shoutout to Ryan Weaver.

What if we do Event Storming in our API Platform projects ? (Gregory Planchat)

Event Storming

Event Storming is a collaborative workshop technique that brings together both users and developers in the same room. This methodology shines a light on misunderstandings that often exist between business stakeholders and technical teams.

The beauty of Event Storming lies in its simplicity: it uses physical post-it notes to encourage different team members to exchange ideas, see each other, share knowledge, meet face-to-face, and confront their understanding of the business domain.

Preparation

The Event Storming process follows a structured approach with several key steps:

List the events - Start by identifying all the significant events that happen in your business domain
Organize the events - Arrange these events in a chronological or logical order
Set up the commands - Identify what actions trigger each event
Set up the actors - Determine who or what initiates each command
Green post-its - Add the data necessary for users to make decisions
Add external systems - Include third-party systems that interact with your domain
Aggregates - Group related events and commands into cohesive business concepts

The team mentioned that they conducted multiple sessions "until no one had any more questions, whether from the technical team or the business team." It's a self-documenting process that can be repeated as the business evolves.

Advantages

Event Storming brings several concrete benefits to development teams:

Process documentation - The workshop naturally creates living documentation of your business processes
Facilitated onboarding - New team members can quickly understand the domain by looking at the Event Storming artifacts
Reveals uncertainties - Hidden assumptions and unclear requirements surface during the collaborative sessions

With API Platform

The Anemic Model Problem

Most applications suffer from what's called the anemic model anti-pattern, where:

Business logic is scattered across numerous services
Loss of user intention tracking
Entities become mere data containers with getters and setters

Typically, when you want to modify information in your entity, you call a setter method. This often happens across multiple services and classes, hence the "business logic disseminated in numerous services" problem.

The intention is essential for third-party systems to understand what actually happened in your application.

Rich Models

The alternative approach uses rich domain models that:

Require significant cost - More complex to implement initially
Require detailed application understanding - Team needs deep domain knowledge
Guarantee consistency over time - Business rules are enforced at the model level
Apply business constraints - Validation logic lives where it belongs
Centralize business logic - Everything related to a concept lives in one or two classes
The model guarantees integrity - Invalid states become impossible

With a rich model, all changes happen within the entity itself, keeping the business logic centralized and coherent.

The CRUD Problem

Traditional CRUD operations are:

Limited to 4 operations (Create, Read, Update, Delete)
SQL-centric thinking
Tools like PostgREST generate REST APIs automatically but provide little business value

To do better, we can leverage the power of API Platform's State Providers and State Processors.

But how do we preserve intention in our application?

The solution follows this flow:
Repository → EventBus → Event → Handler

Model Modification

The team implemented a pattern with three key methods in their entities:

recordThat() - Records that an event occurred (e.g., "a deployment was launched")
apply() - Applies the modifications related to the event (e.g., updates the deployment date)
releaseEvents() - A cleanup step that happens during the save process, just before persist/flush, then dispatches events throughout the application

This approach ensures that every business action is captured as a meaningful event, preserving the user's intention and providing a clear audit trail of what happened in the system.

Results

The team reported several concrete improvements after implementing this approach:

An API and codebase that better resembled the company's business domain
User intention was preserved throughout the application lifecycle
Better understanding of actions performed in the application, both for developers and business stakeholders

Scaling Databases (Tobias Petry)

Tobias Petry shared insights on database scaling strategies. His talk highlighted why scalability issues usually originate at the database level and walked through the most common solutions, their advantages, and their pitfalls.

Solutions

There is no silver bullet: every application has its own constraints. Still, several well-known strategies exist:

Find and fix slow queries

Before considering infrastructure, always check the basics. Tools like mysqlexplain.com can help detect inefficient queries and suggest improvements.
Cache results

Serving cached responses drastically reduces the load on the database and avoids repeating costly operations.
Vertical scaling (bigger machines)

Sometimes the simplest option is to scale up: move the database to a more powerful server. However, this approach quickly reaches physical and financial limits.
Multi-master replication

In this setup, several servers accept both reads and writes. It improves write scalability but creates the risk of conflicts when parallel writes occur. Conflict resolution strategies can mitigate this, but complexity grows with the number of nodes.
Read replication

Here, a single primary node handles writes, while replicas serve read queries.
- Synchronous replication ensures that changes are propagated to all replicas before acknowledging the write. This guarantees consistency but adds latency, as every replica must confirm.
- Asynchronous replication acknowledges the write immediately and updates replicas later. It reduces latency but risks temporary inconsistency between nodes. In practice, most applications tolerate eventual consistency. A cache layer in front of the primary often hides replication lag. Still, studies show that 90–98% of applications encounter latency issues if relying only on replicas for reads.
Sharding

Sharding distributes data across multiple databases. This enables theoretically infinite scalability. For example, users might be split across shards based on their ID.

The challenge comes with cross-shard queries: if you need to fetch all orders of a user across multiple shops, and users and shops are sharded differently, you must query several shards and aggregate results manually. Some companies even introduce shards of shards, adding another layer of complexity.

Because of this overhead, sharding is usually reserved for very large-scale systems. For most use cases, read replication is sufficient.

In general, these strategies are designed for CRUD workloads. Analytical queries (dashboards, reports) are harder to scale with a standard relational database. Developers can explore resources like sqlfordevs.com (free course on making analytics faster) or specialized systems such as TimescaleDB.

Sounds complicated

Tobias emphasized a crucial point: scaling decisions must be made before hitting database bottlenecks. Once data is structured and scaling strategies are in place, rolling back becomes almost impossible. Database architecture is one of those areas where it is far easier to make the right decision early than to correct mistakes later.

API Platform, JsonStreamer and ESA for skyrocketing API (Mathias Arlaud)

Slides of this talk are available : https://www.canva.com/design/DAGyYPxkygw/M1RzOiv8_cMp0Pa7Mh0u4g/view

Storytelling: imagine a bookstore. A customer orders all Symfony-related books. The bookseller tries to gather them all, but it's heavy—takes time, lots of books. The second time, the same request, but the pile is so large that the bookseller collapses under the weight.

In the API world, JSON is king.

At the heart of our stack is API Platform, which relies on Symfony’s Serializer. But sometimes the Serializer is like that bookseller: it works well until the load becomes too heavy.

Serialization / Normalization in Symfony

Serialization in Symfony (and in API Platform) involves turning PHP objects into arrays or scalar values, then encoding to formats like JSON or XML. Normalization transforms the internal object graph into a neutral data structure (arrays, scalars), applying metadata such as groups or attributes. Encoding then converts that structure into the final JSON string. The reverse process (denormalization) handles input JSON → arrays → objects.

When objects or collections are small, this works fine. But with thousands of items, large graphs, deep associations, and nested arrays, memory usage and time-to-first-byte degrade. Serialization becomes a bottleneck.

Streaming as a solution

Instead of building a huge in-memory structure, streaming emits JSON pieces incrementally. You only keep in memory what’s necessary at each moment.

Symfony 7.3 introduces the JsonStreamer component for that purpose.

Some key features:

Works best with POPOs (Plain Old PHP Objects) having public properties, without complex constructors.
The #[JsonStreamable] attribute can be used on classes to mark them as streamable. This also allows pre-generation of code during cache warm-up.
Use the TypeInfo component (link) to describe types of collections and objects (e.g., Type::list(Type::object(MyDto::class))). This helps JsonStreamer guess the shape of the output JSON without loading everything in memory.

Here is a code snippet from the Symfony documentation showing basic usage:

// Example class
namespace App\Dto;

use Symfony\Component\JsonStreamer\Attribute\JsonStreamable;

#[JsonStreamable]
class User
{
    public string $name;
    public int $age;
    public string $email;
}

// In controller
use Symfony\Component\JsonStreamer\StreamWriterInterface;
use Symfony\Component\TypeInfo\Type;
use Symfony\Component\HttpFoundation\StreamedResponse;

public function retrieveUsers(StreamWriterInterface $jsonStreamWriter, UserRepository $userRepository): StreamedResponse
{
    $users = $userRepository->findAll();
    $type = Type::list(Type::object(User::class));
    $json = $jsonStreamWriter->write($users, $type);
    return new StreamedResponse($json);
}

Benchmarks & comparisons

For a dataset of 10,000 objects:

Method	Time	Memory usage / footprint (rough / relative)
Serializer (traditional)	~ 204 ms	~ 16 MB (grows with size)
JsonStreamer	~ 87 ms	~ 8 MB (much more constant)

Challenges with metadata, JSON-LD and how API Platform adapts

API Platform adds metadata, JSON-LD contexts, property metadata, etc. That adds overhead in serialization. To integrate JsonStreamer while preserving rich metadata:

They use PropertyMetadataLoader extension points to provide metadata to JsonStreamer. This lets JsonStreamer know property names, whether they're exposed, etc., without traversing the full object tree in memory.

API Platform

Use of ValueTransformers that can transform any value at runtime. But caution: heavy logic in transformers can degrade performance (they run per value).

Symfony
+1

Use of ObjectMapper to convert entities (e.g., Doctrine objects) into POPOs (DTOs) that are suitable for streaming. This helps because entities often have lazy properties, proxies, relations etc., which complicate streaming.

ESA (Edge Side APIs) pattern

Edge Side APIs refers to breaking large JSON payloads into smaller, progressive calls or chunks, often delivered from the edge / CDN to improve perceived performance, especially in high latency/slow networks. In context of this talk:

Instead of sending one huge JSON structure, partition or paginate so the client can start receiving some data quickly.

Combine with streaming so that parts of the response start being delivered early (TTFB improves).

Good user experience: user sees something quickly rather than waiting for full load.

Takeaways

Serializer works, but for large data sets it becomes inefficient.

JsonStreamer gives significant improvements in both memory usage and time to first byte.

When you have metadata layers (API Platform, JSON-LD), use the extension points provided to plug streaming without losing features.

Avoid heavy computations / transformations in runtime‐hot paths (e.g., ValueTransformers).

Design your API knowing these options early, because once core serialization path is deeply embedded, changing is hard.

Benchmarks & comparisons

For a dataset of 10,000 objects:

Method	Time	Memory usage / footprint
Serializer (traditional)	~204 ms	~16 MB (grows with size)
JsonStreamer	~87 ms	~8 MB (much more constant)

Challenges with metadata, JSON-LD and how API Platform adapts

API Platform adds metadata, JSON-LD contexts, and property metadata. That overhead makes serialization heavier. To integrate JsonStreamer while keeping these features:

Use PropertyMetadataLoader extension points to provide metadata to JsonStreamer. This tells it which properties to expose, without traversing the full object tree.
Use ValueTransformers to adjust values at runtime. But beware: heavy logic here will degrade performance, since transformers run for every value.
Use ObjectMapper to convert entities (e.g., Doctrine objects) into POPOs (DTOs) that are easier to stream.

ESA (Edge Side APIs) pattern

Edge Side APIs (ESA) refers to breaking large JSON payloads into smaller, progressive chunks, often delivered from the edge or a CDN to improve perceived performance, especially in high-latency or slow networks.

In practice:

Instead of sending one huge JSON structure, partition or paginate so the client starts receiving data earlier.
Combine with streaming so that parts of the response arrive incrementally, improving time-to-first-byte.
The user experience is better: data appears quickly instead of waiting for everything.

Takeaways

Symfony’s Serializer is fine for small to medium datasets.
JsonStreamer provides significant improvements in memory usage and TTFB.
API Platform integrates it through extension points (PropertyMetadataLoader, ValueTransformers, ObjectMapper).
Avoid heavy runtime transformations for best performance.
Design your API with these options in mind early—serialization decisions are very difficult to change later.

Credits

Cover image by Nicolas Detrez

SymfonyLive Paris 2025 : Ce qu’il faut retenir

Thérage Kévin — Wed, 02 Apr 2025 11:53:54 +0000

J’ai eu la chance d’assister au SymfonyLive Paris 2025, et voici un résumé des annonces, conférences et tendances clés à retenir !

Retrouvez les slides sur ce merveilleux dépôt (Merci Romain Gautier🙏) : https://github.com/SymfonyLive/paris-2025-talks)

Keynote : Scaling to 0 (🎤 Fabien Potencier)

🚀 Qu'est-ce qu'un projet Open Source ?

Un projet open source, ce n'est pas seulement du code. Voici la hiérarchie des priorités :

Communauté
Documentation
Code

Une communauté active et une documentation solide sont essentielles pour assurer la pérennité d’un projet OS.

Avec le temps, Symfony a intégré une nouvelle priorité : l’expérience développeur (DX). La hiérarchie évolue donc ainsi :

Communauté
Documentation
Expérience développeur (DX)
Code

🏗️ Comment créer une application Symfony simple ?

Suite aux débats dans la communauté Laravel sur la complexité d’installation et la multitude de dépendances requises pour démarrer un projet, Fabien s’est posé la question :

"Quelle est l'application Symfony la plus simple possible ?"

En réponse, Symfony propose désormais trois nouveaux points d’entrée, permettant de commencer petit et d’évoluer progressivement.

🔹 Symfony Hello

Une version "Hello world" ultra-minimaliste de Symfony, offrant la puissance du full-stack framework avec une empreinte réduite.

Échelle	Taille d'équipe	Structuration	Conventions
Fichier unique	Solo dev	Aucune	Aucune

✅ Idéal pour :

Rapidité
Flexibilité
Prototypage (PoC) minimaliste
Projets personnels non maintenus

🔹 Symfony Solo

Symfony sans Flex, offrant un contrôle total sur l’architecture.

💡 Il permet un front controller CLI & HTTP grâce au composant Runtime :

$mode = PHP_SAPI === 'cli' ? 'console' : 'http';

Échelle	Taille d'équipe	Structuration	Conventions
Petits/moyens projets	Solo dev	Aucune (personnalisable)	Aucune (liberté totale)

✅ Idéal pour :

Commencer en toute légèreté
Scalabilité progressive (scale as you go)
Applications mono-tâche
Projets personnels avancés
PoC élaborés

🔹 Symfony Team

Le framework full-stack classique, conçu pour les projets de grande envergure.

Échelle	Taille d'équipe	Structuration	Conventions
Moyens à grands projets	Équipe de devs	Standardisée	Documentées

✅ Idéal pour :

Industrialisation
Travail collaboratif
Maintenance à long terme
Projets professionnels

⚙️ Un petit teaser à propos de Symfony 8

Disparition des fichiers XML pour la configuration des routes, désormais remplacés par des fichiers PHP.

🤖 Hot Takes sur les LLMs

Les LLMs ne remplaceront pas les développeurs.
Ce sont d’excellents stagiaires : disponibles 24/7, polis… mais parfois incohérents !
Très utiles contre le syndrome de la page blanche.
Claude s’avère particulièrement efficace pour la génération de code et de documentation.
Possibilité d’utiliser les LLMs pour :
- Mise à jour automatique du code (avec prudence).
- Documentation des PRs pour améliorer la revue de code.

Symfony ObjectMapper Component (🎤 Antoine Bluchet)

Après une partie d'historique sur l'arrivée du composant dans Symfony. Antoine a démarré par présenter le ce qui existait dans les autres langages et en PHP.

🏗️ Object Mapping dans d'autres languages

Spring : jackson
.Net : automapper
Java :
- modelmapper
- Java Map Struct
Ruby : Ruby Object Mapper (ROM)

🛠️ Etat du mapping en d'objet en PHP

Valinor : offre du mapping et bien plus (ce qui n'est pas une bonne chose selon Antoine)
Automapper (JoliCode) : Fonctionne sur le principe de génération de classe PHP pour mapper les objets
MicroMapper (SymfonyCasts) : version simpliste.
et bien d'autres

🎯 Mapping vs Hydratation

Hydratation : remplir un objet avec des données.
Mapping : transformer un objet en un autre objet.

💡 Contrairement au serializer, le mapping en PHP permet une meilleure séparation des responsabilités et une meilleure intégration avec Symfony.

Le composant

Le composant offre une approche simple via des attributs permettant de faire un mapping rapide via des attributs.

vous pouvez retrouver la Pull-Request ici

Exemple :

use Symfony\Component\ObjectMapper\ObjectMapper;
use Symfony\Component\ObjectMapper\Attributes\Map;

// This maps class `A` to class `B`.
#[Map(B::class)]
class A
{
    // This maps A::foo to B::bar.
    #[Map(target: 'bar')]
    public string $foo;

    // This calls ucfirst on A::transform
    #[Map(transform: 'ucfirst')]
    public string $name;

    // This doesn't map A::bar if it's value is falsy.
    #[Map(if: 'boolval')]
    public bool $bar = false;
}

$mapper = new ObjectMapper();
$mapper->map(new A);

PostgreSQL pour vos besoins NoSQL (🎤 David Buchmann)

Après une brève introduction et un rappel sur le fait que le NoSQL n'est pas clairement défini alternant entre base de donnée non-relationnel et le fait qu'une base de donnée relationnel permette aussi de stocker des élements sans relation, il a fait le tours des fonctionnalité de PostGreSQL et de MySQL (ce qui a été une petite surprise compte tenu du titre) permettant de stocker et de requête du JSON.

🔍 Type de colonne JSON vs JSONb

En PostGreSQL deux types de colonnes son proposés JSON et JSONb avec leurs avantages et leurs incovénients.

	Avantages	Inconvénients
JSON	Préserve l'ordre des clés dans l'objet	stocké sous forme de chaîne de caractères aucune optimisation des caractères répétés accepte du JSON invalide (garde les clés dupliquées)
JSONb	format binaire optimisé Performant pour les requêtes	Aucune mention faite

En dehors de cas d'utilisation non standard, il est préférable d'utiliser JSONB.

⚙️ Opérateurs utiles

Soit le JSON suivant :

{"author": "David"}

-> : extrait une information JSON. ie : renvoie "David"
->> : extrait une donnée native tout en etant 2.5 fois plus rapide. ie : renvoie David

L'opérateur -> existe aussi pour MySQL mais il faut préciser le JSONPath :
->'$.author'

Ajouter un index sur un champ json

Il est possible d'ajouter un index sur un champ JSON via l'instruction

CREATE INDEX name ON json_column ((json_column->>'author'));

Ce qui améliore le temps de requête considérablement.

Générer une colonne à partir d'une propriété JSON

Il est possible d'extraire et de générer une colonne à partir d'une propriété JSON via l'instruction

CREATE TABLE foo (
    # ...
    author VAR_CHAR(255) generated always as (json_column->>'author') stored,
    # ...
);

l'extraction d'une date est compliqué est nécessite de passer par une procédure stockée.

Fonctions utiles

contient :
- json_column @> '{"author": "David"}'
la clé existe :
- json_column ? 'author'
- jsonb_exists(json_column, 'author')
au moins une clé existe :
- json_column ?| array['author', 'it_does_not_exists']
- jsonb_exists_any(json_column, array['author', 'it_does_not_exists'])
toutes les clé existent :
- json_column ?& array['author', 'it_does_not_exists']
- jsonb_exists_all(json_column, array['author', 'it_does_not_exists'])

Passkeys pour une authentification fluide et sécurisée (🎤 Rémi Janot)

🔐 Problèmes des mots de passe

Créés dans les années 60, ils sont devenus vulnérables.
Brute-force, phishing, réutilisation…
HaveIBeenPwned révèle l’ampleur des fuites de données.

🔑 2FA / MFA

Réside sur 3 piliers :

Ce que l'on sait (mot de passe).
Ce que l'on a (téléphone, clé de sécurité).
Ce que l'on est (empreinte digitale, reconnaissance faciale).

🌍 WebAuthn

API JS, supportée par 96 % des navigateurs.
S'appuie sur les 3 piliers du 2FA / MFA

💻 Démonstration

La démonstration d'un intégration d'un système d'authentification WebAuthn a ensuite été présentée par Rémi avec une explication étape par étape de ce qui était transmis au serveur (payload JSON, request/response).

Retrouvez le dépôt du projet de démonstration ici

Symfony UX : Points forts de 2024 et perspectives d’avenir (🎤 Simon André)

5 ans après : où en est Symfony UX ?

👨‍💻 Symfony UX core team

Officialisation de la core team Symfony UX avec pour membres :

Ryan Weaver
Kévin Bond
Hugo Alliaume
Simon André
Mathéo Daninos

📌 Adoption

Utilisé par Symfony, EasyAdmin, PrestaShop, Sylius, SensioLabs, et même le ministère de l’Intérieur.

📊 Quelques chiffres

2022 → 800 000 téléchargements
2023 → 4 000 000 téléchargements
2024 → 1 500 000 téléchargements

Les packages UX les plus populaires :

95 000/semaine : Twig Component.
50 000/semaine : UX Icons.
40 000/semaine : Live Component.

🔮 UX en 2025

Typony Express : Création d'un jeu https://zty.pe/ entièrement avec Symfony UX comme une expérimentation et avec une documentation.
Refonte du site UX.
Un UX Bundle unique pour simplifier l’écosystème et l'ajout de nouveau "modules" UX.
UX v3 prévu pour l’été 2025.
Symfony 8 : retour à une synchronisation des versions.

Rôles & Permissions : Marque blanche et Feature Flipping (🎤 Florian Bogey)

Florian nous as montré comment Rôle et Permissions peuvent être utilisé de concert pour permettre la mise en place d'un marque blanche et d'un mécanisme de feature flag/flipping/toggle/whatever you may call something that activate or not a feature on your website.

🎭 Rôles vs Permissions

Rôle : catégorie utilisateur statique.
Permission : règle métier dynamique.

Symfony gère les permission via les Voters.
Il est possible de cumuler les attributs #[IsGranted()] pour différencier contrôles d'accès par les rôles des contrôles d'accès par permissions.

Exemple :

use Symfony\Component\Security\Http\Attribute\IsGranted;

final class FooController {

    #[Route('/foo/{id}', name: 'foo')]
    #[IsGranted('ROLE_ADMIN')]
    #[IsGranted('foo_voter', 'id')]
    public function __invoke(int $id): Response
    {
        // ...
    }
}

🗳 Voter

Les voters peuvent être configurés selon 4 stratégies :

Affirmative (par défaut) : Au moins un voter autorise l'action.
Consensus : nécessite de voter qui autorise l'action que de voter qui ne l'interdise.
Unanime : autorise l'action si aucun voter ne l'a interdite.
Priority : renvoie la décision du premier voter qui ne s'est pas abstenu en s'appuyant sur la priorité définie dans les services.

🏢 Gestion de clients exigeants

Deux besoins principaux :

Marque blanche → Identité visuelle, branding personnalisé.
Feature Flipping → Activer/désactiver des fonctionnalités par client.

💮 Marque blanche

Définition : La marque blanche est un modèle commercial qui permet à une entreprise de vendre des produits ou des services conçus par une autre entreprise sous sa propre marque.

Afin de pouvoir avoir une application "Multi-tenant" (comprendre un seul code source pour plusieurs marques/clients différents), Florian nous as expliqué qu'il était nécessaire que chaque dispose de sont propre fichier d'environnement.

C'est rendu possible grâce

l'ajout d'une variable d'environnement côté serveur web (SetEnv apache et set nginx)
une légère modification du front controller (le fichier public/index.php) de Symfony afin d'ajouter la logique permettant le chargement du bon fichier DotEnv.

(new DotEnv())->loadEnv(sprintf('%s/.env.%s', dirname(__DIR__), $context['APP_SOME_NAME']));

une extension TWIG pour transmettre les variables d'environnement nécessaire a TWIG.

🔄 Feature Flipping

Définition : Permettre d'activer/désactiver une fonctionnalité ou des partie d'une application sous certaines conditions.

Après une présentation de plusieurs alternative et bundle permettant un feature flipping, Florian a présenté la solution maison qu'ils ont mis en place chez GL Events (retrouver les slides de Florian ici.

Async avec Messenger, AMQP et Mercure

🔄 Rappel sur Messenger

Permet d’exécuter des tâches asynchrones.
Transports disponibles : sync, in-memory, AMQP…
Messages stockés dans une queue.
Gestion avec un superviseur (systemd, supervisord).

💡 Conseil : Pour les imports async, ne stockez pas les fichiers en BDD/queue, mais sur un disque partagé.

📡 Donner du feedback en temps réel (exemple : import)

❌ Mauvaises solutions

XHR Polling : inefficace.
WebSockets : complexe et lourd à maintenir.

✅ Solution moderne : Mercure

Surcouche à SSE (Server-Sent Events).
Full duplex et optimisé pour les updates en temps réel.
Installation via Composer.
Connexion JS via new EventSource() présent nativement dans les navigateurs.

🔐 Sécurité

Authentification JWT intégrée.
Publisher authentifié.
Subscriber anonyme ou non.

Symfony UX + Turbo + SSE

{{ turbo_stream_listen('csv:' ~ importId) }}

Permet de recevoir des mises à jour sans écrire une ligne de JS !

Atteindre la qualité d’une SPA avec HTMX et Twig

🌍 HTMX : une alternative aux SPA

Créé par Carson Gross en 2020.
50 KB, plus léger que jQuery.

🛠️ Fonctions principales

hx-get / hx-post : appels Ajax.
hx-trigger : changement d’événement (once, throttle, revealed…).
hx-target : où afficher la réponse Ajax.
hx-swap : méthode d’insertion (innerHTML, outerHTML, delete…).
hx-boost : transforme tous les liens en requêtes AJAX.

📌 Twig et animations CSS

Utilisation de renderBlock() pour ne rendre qu’un bloc spécifique d’un template.
Morphing des éléments via un ID conservé.

Du Lego de composants pour un bundle Gotenberg

📜 Génération de PDF en Symfony

Utilisation du bundle Gotenberg.
Permet de convertir HTML en PDF facilement.
Exemples et démonstrations disponibles sur Medium.

Symfony & Doctrine Migrations: Validation in CI

Thérage Kévin — Thu, 05 Sep 2024 10:13:59 +0000

I had the opportunity to work on a project with a team that was relatively new to Doctrine migrations. To help them get used to it, and to discard the possibility of having pull (or merge) requests with changes to doctrine entities without generating a migration.

Here is how I did it. I hope you'll enjoy it!

How Doctrine Migrations works

When generating the migration, Doctrine will make a delta between its mapping and the current schema of the database. With this delta in "mind" (dare I say 😉) it will generate a migration file with two main methods :

up applies the SQL commands to fill the gap between the current database schema and its mapping. Used to deploy changes in the schema of your database.
down allows to revert the migration with the SQL commands needed to "negate" the changes made in the up method. Used to roll back changes in the schema of your database.

The magic trick

There is currently no way to easily check if a migration has not been generated. Having this code merged could lead to a database schema being out of sync with your entity mapping and so resulting in a server error.

The keywords in the above description are migration files. I'll use the fact that, running the command bin/console doctrine:migration:diff will result in a newly generated file and will fail if there are no changes to apply.

Knowing the list of existing files before the execution of that command, and then running it, can let me know that there are changes that were not committed to a migration file in this pull (or merge) request.

Steps to do

Create your database
Run your existing migrations
Then run the step to check for missing changes (see below)

Advantages

Testing that your migrations does not fail
Ensure database schema consistency with Doctrine's mapping

You want the code snippet right!?

Here is the bash code :

#!/bin/bash

set -e
set -o pipefail

# run doctrine migration diff to check if there is a new migration file generated and check last exit code
if [[ -z $(bin/console doctrine:migrations:diff -n --quiet) ]]; then
    echo "Error ! bin/console doctrine:migration:diff found a new migration which must not be the case.";
    # cat last file (should be the newly generated one)
    cat $(ls -Art migrations/*.php | tail -n 1);
    # remove that file (just in case to comply with my paranoïac side)
    rm -f $(ls -Art migrations/*.php | tail -n 1);
    exit 1;
else
    exit 0;
fi

And that's it! You can now ensure that each pull (or merge) request has working migrations, with no pending changes left out of the migrations!

Ok but why not use `bin/console doctrine:schema:validate`?

The reason was that the project we were working on was using doctrine's schema_filter configuration to filter out some tables we did not want to deal with (project-related inconvenience).

The problem with bin/console doctrine:schema:validate was that it did not take care of the configuration, and so was dumping changes (trying to delete all the "normally" filtered out tables) not related to what we wanted.

A colleague told me that this is a known issue that might be fixed soon (https://github.com/doctrine/migrations/issues/1406).

Thank you for reading this article and please leave your comments if you have any questions!

Credits

Cover image: Unsplash by Ethan Weil