{
    "version": "https://jsonfeed.org/version/1.1",
    "title": "Jérémy DECOOL - Articles PHP (FR)",
    "home_page_url": "https://www.jdecool.fr/",
    "feed_url": "https://www.jdecool.fr/feed/php.json",
    "icon": "https://www.jdecool.fr/img/jdecool.jpg",
    "favicon": "https://www.jdecool.fr/img/jdecool-64.jpg",
    "language": "fr",
    "authors": [{
        "name": "Jérémy DECOOL",
        "url": "https://www.jdecool.fr/",
        "avatar": "https://www.jdecool.fr/img/jdecool.jpg"
    }],
    "author": {
        "name": "Jérémy DECOOL",
        "url": "https://www.jdecool.fr/",
        "avatar": "https://www.jdecool.fr/img/jdecool.jpg"
    },
    "items": [
        
        {
            "id": "de3bcc05d90ac0a5236af2094e5e094e",
            "title": "Filtrer une collection Doctrine",
            "content_html": "<p>Quand on doit filtrer une collection Doctrine, le premier réflexe est d’utiliser la méthode <code>filter()</code>. Simple et pratique, le code est plus court et lisible qu’une boucle traditionnelle.</p>\n\n<figure class=\"highlight\"><pre><code class=\"language-php\" data-lang=\"php\">#[ORM\\Entity]\nclass Project\n{\n    #[ORM\\OneToMany(targetEntity: Task::class)]\n    private Collection $tasks;\n\n    public function getPendingTasks(): Collection\n    {\n        return $this-&gt;tasks-&gt;filter(\n            static fn (Task $task): bool =&gt; !$task-&gt;isDone(),\n        );\n    }\n}</code></pre></figure>\n\n<p>Néanmoins cette méthode de filtrage peut ne pas être sans conséquences.</p>\n\n<!--more-->\n\n<p>Les collections Doctrine sont rarement utilisées comme bibliothèques de collections. Elles sont généralement utilisées avec le composant ORM pour manipuler la base de données. Si l’on reprend le code précédent, <code>$project</code> est une entité Doctrine qui possède une relation avec une entité <code>Task</code>. Or si un projet est associé à de nombreuses tâches, la méthode <code>filter()</code> peut être inefficace car elle va nécessiter la récupération et l’hydratation de toutes les données (potentiellement des milliers) avant de les parcourir une à une pour filtrer les tâches non terminées. Cela peut s’avérer être un désastre pour les performances.</p>\n\n<p>C’est un des problèmes de gestion des collections de données avec les ORM bien moins connu que le <a href=\"https://www.jdecool.fr/blog/2015/12/17/le-probleme-n+1.html\">problème N+1</a> car il est plus discret puisqu’il n’y a qu’une seule requête SQL qui est exécutée. Le reste se passe en mémoire.</p>\n\n<p>Il est alors tentant d’extraire cette logique de filtrage dans une méthode de <em>repository</em> pour éviter de charger toutes les tâches en mémoire et de le faire via une requête SQL. C’est dommage, surtout lorsque l’on souhaite conserver la sémantique objet de notre appel et permettre de récupérer toutes les tâches non terminées d’un projet à partir de l’objet <code>Project</code> lui-même.</p>\n\n<p>Il existe pourtant une seconde méthode des collections Doctrine (si la collection implémente l’interface <code>Doctrine\\Common\\Collections\\Selectable</code>) permettant de filtrer les éléments, mais qui elle est bien moins connue : la méthode <code>matching</code>. Cette dernière prend en paramètre un objet <code>Doctrine\\Common\\Collections\\Criteria</code> qui permet de définir les conditions de filtrage.</p>\n\n<figure class=\"highlight\"><pre><code class=\"language-php\" data-lang=\"php\">use Doctrine\\Common\\Collections\\Criteria;\n\npublic function getPendingTasks(): Collection\n{\n    $criteria = Criteria::create()\n        -&gt;where(Criteria::expr()-&gt;eq(&#39;done&#39;, false));\n    \n    return $this-&gt;tasks-&gt;matching($criteria);\n}</code></pre></figure>\n\n<p>La différence est que <code>Criteria</code> n’est pas du code exécutable, mais la description d’un filtre. De ce fait, si l’on utilise une collection mémoire de type <code>Doctrine\\Common\\Collections\\ArrayCollection</code>, la méthode <code>matching</code> va fonctionner de la même manière que la méthode <code>filter</code>. Par contre, dans un contexte ORM, les collections sont généralement des objets de type <code>Doctrine\\Common\\Collections\\PersistentCollection</code>, la méthode <code>matching</code> va exécuter une requête SQL pour filtrer les éléments directement depuis la base de données.</p>\n\n<p>Il y a néanmoins quelques points d’attention à avoir en utilisant <code>matching</code> avec <code>PersistentCollection</code> :</p>\n<ol>\n  <li>l’exécution SQL ne sera déclenchée que si la collection <code>Project::$tasks</code> n’a pas encore été initialisée. Dans le cas contraire, la méthode <code>matching</code> itérera sur la collection en mémoire,</li>\n  <li>la méthode <code>matching</code> retournera une nouvelle collection détachée.</li>\n</ol>\n\n<p>Maintenant, vous vous demandez peut-être s’il est encore utile d’utiliser <code>filter</code> ? La réponse que j’ai envie de donner est : “ça dépend”. Tout dépendra de la donnée qui est manipulée. Faire un <code>matching</code> avec la légère complexité que cela implique est pertinent sur des grosses collections gérées par Doctrine ORM. Sur des collections hors ORM ou sur des petites collections persistées <code>filter</code> pourra faire l’affaire.</p>\n",
            "summary": "Quand on doit filtrer une collection Doctrine, le premier réflexe est d’utiliser la méthode filter(). Simple et pratique, le code est plus court et lisible qu’une boucle traditionnelle. Néanmoins cette méthode de filtrage peut ne pas être sans conséquences.",
            "url": "https://www.jdecool.fr/blog/2026/08/29/filtrer-une-collection-doctrine.html",
            "date_published": "2026-08-29T00:00:00+02:00",
            "tags": ["php","doctrine","orm","sql","performance"],
            "language": "fr"
        },
        
        {
            "id": "78fb73dcf5286be00d78095967ec975e",
            "title": "Profilez vos tests PHPUnit avec OpenTelemetry",
            "content_html": "<p>Un projet de développement informatique qui grossit, c’est une base de code qui grossit par la même occasion et la batterie de tests qui évolue en conséquence. On ajoute des tests semaine après semaine, les temps d’exécution s’allongent. Et puis, à un moment, la CI s’arrête net: <code>Allowed memory size exhausted</code>. Le premier réflexe est alors d’augmenter la mémoire allouée à PHP. Et ce cycle peut continuer un certain temps, jusqu’au moment où l’on atteint des seuils critiques.</p>\n\n<!--more-->\n\n<p>Je l’ai rencontré dans plusieurs expériences professionnelles. Corriger des problèmes de mémoire est compliqué et l’outillage restreint. On est donc aveugle, on ne sait pas quels tests consomment de la mémoire, lesquels prennent du temps à s’exécuter. Monitorer une application en production est une bonne pratique, pourquoi n’en serait-il pas de même pour nos tests ?</p>\n\n<p>Pour l’observabilité de nos applications de production, un standard est en train de s’imposer: <a href=\"https://opentelemetry.io \" target=\"_blank\" rel=\"noopener noreferrer\">OpenTelemetry</a>. Pourquoi, alors, ne pas utiliser ce dernier pour également suivre ce qu’il se passe sur nos tests: produire des traces et des métriques que nous pourrions analyser ?</p>\n\n<p>Il existe d’ailleurs une bibliothèque pour intégrer de l’observabilité dans nos tests PHPUnit avec OpenTelemetry: <a href=\"https://packagist.org/packages/flow-php/phpunit-telemetry-bridge \" target=\"_blank\" rel=\"noopener noreferrer\">flow-php/phpunit-telemetry-bridge</a>. Il s’agit d’une extension PHPUnit qui collecte la télémétrie de votre suite de tests et l’exporte vers n’importe quel <em>backend</em> compatible OTLP.</p>\n\n<p>Pour l’installer, rien de plus simple:</p>\n\n<figure class=\"highlight\"><pre><code class=\"language-bash\" data-lang=\"bash\">composer require --dev flow-php/phpunit-telemetry-bridge</code></pre></figure>\n\n<p>Il restera ensuite à ajouter la configuration nécessaire dans PHPUnit:</p>\n\n<figure class=\"highlight\"><pre><code class=\"language-xml\" data-lang=\"xml\">&lt;?xml version=&quot;1.0&quot; encoding=&quot;UTF-8&quot;?&gt;\n&lt;phpunit&gt;\n    &lt;!-- ... --&gt;\n    &lt;extensions&gt;\n        &lt;bootstrap class=&quot;Flow\\Bridge\\PHPUnit\\Telemetry\\TelemetryExtension&quot;&gt;\n            &lt;parameter name=&quot;service_name&quot; value=&quot;phpunit-opentelemetry&quot;/&gt;\n            &lt;parameter name=&quot;transport&quot; value=&quot;curl&quot;/&gt;\n            &lt;parameter name=&quot;endpoint&quot; value=&quot;http://localhost:4318&quot;/&gt;\n            &lt;parameter name=&quot;emit_traces&quot; value=&quot;true&quot;/&gt;\n            &lt;parameter name=&quot;emit_metrics&quot; value=&quot;true&quot;/&gt;\n            &lt;parameter name=&quot;emit_test_spans&quot; value=&quot;true&quot;/&gt;\n            &lt;parameter name=&quot;emit_test_case_spans&quot; value=&quot;true&quot;/&gt;\n            &lt;parameter name=&quot;curl_connect_timeout_ms&quot; value=&quot;1000&quot;/&gt;\n            &lt;parameter name=&quot;curl_timeout_ms&quot; value=&quot;2000&quot;/&gt;\n        &lt;/bootstrap&gt;\n    &lt;/extensions&gt;\n&lt;/phpunit&gt;</code></pre></figure>\n\n<p>Une fois configuré, il ne reste plus qu’à lancer vos tests, les données de télémétrie seront automatiquement envoyées, vous permettant ensuite de les visualiser dans des tableaux de bord.</p>\n\n<center>\n    <img src=\"https://www.jdecool.fr/img/blog/20260601-profilez-vos-tests-phpunit-avec-opentelemetry/phpunit-otel-overview.png\" alt=\"Vue d'ensemble de la télémétrie d'une suite de tests PHPUnit dans un tableau de bord\" />\n</center>\n\n<p>On y retrouvera chaque suite de tests avec le détail de chaque test: sa durée, son empreinte mémoire, son statut.</p>\n\n<center>\n    <img src=\"https://www.jdecool.fr/img/blog/20260601-profilez-vos-tests-phpunit-avec-opentelemetry/phpunit-otel-memory.png\" alt=\"Consommation mémoire des tests PHPUnit visualisée via OpenTelemetry\" />\n</center>\n\n<p>Quelques points d’attention néanmoins. Instrumenter chaque test a un coût. Cela ne sera pas forcément intéressant sur une petite suite de test. C’est surtout lorsque le projet commence à grossir que ce type de donnée a de la valeur et que vous souhaitez arrêter de naviguer à l’aveugle.</p>\n\n<p>Et si vous désirez en savoir plus, n’hésitez pas à consulter <a href=\"https://flow-php.com/documentation/components/bridges/phpunit-telemetry-bridge/ \" target=\"_blank\" rel=\"noopener noreferrer\">la documentation de l’outil</a>.</p>\n",
            "summary": "Un projet de développement informatique qui grossit, c’est une base de code qui grossit par la même occasion et la batterie de tests qui évolue en conséquence. On ajoute des tests semaine après semaine, les temps d’exécution s’allongent. Et puis, à un moment, la CI s’arrête net: Allowed memory size exhausted. Le premier réflexe est alors d’augmenter la mémoire allouée à PHP. Et ce cycle peut continuer un certain temps, jusqu’au moment où l’on atteint des seuils critiques.",
            "url": "https://www.jdecool.fr/blog/2026/06/01/profilez-vos-tests-phpunit-avec-opentelemetry.html",
            "date_published": "2026-06-01T00:00:00+02:00",
            "tags": ["php","phpunit","opentelemetry","observabilite","tests"],
            "language": "fr"
        },
        
        {
            "id": "be66407ac8e0d104bc8f3592d751b7ce",
            "title": "Faire des requêtes CTE avec Doctrine ORM en PHP",
            "content_html": "<p>J’ai déjà évoqué sur ce blog que <a href=\"https://www.jdecool.fr/blog/2026/02/18/boring-technology-les-bases-de-donnees-relationnelles.html\">le développement “moderne” avec les ORM masque les fonctionnalités avancées des SGBD</a> au point que dorénavant les développeurs ne maitrisent et ne connaissent guère plus que le classique <code>SELECT ... FROM ... WHERE ...</code>.</p>\n\n<p>Dans les mécanismes méconnus et qui pourtant, pourrait permettre de soulager certains traitements applicatifs, on retrouve les CTE (<em>Common Table Expressions</em>). Voyons comment les utiliser avec Doctrine ORM en PHP.</p>\n\n<!--more-->\n\n<p>Commençons par expliquer ce qu’est une CTE. Il s’agit d’une sous-requête utilisable comme une table temporaire. C’est une technique utile pour décomposer des requêtes complexes, éviter la duplication de sous-sélections ou écrire des requêtes récursives.</p>\n\n<p>En presque 20 ans d’expérience professionnelle, j’ai très rarement eu l’occasion d’en voir dans le code que je peux être amené à parcourir quotidiennement. Prenons par exemple, un blog où les articles sont rattachés à des catégories, ces dernières organisées sous forme arborescente sous la forme <code>Category(id, label, parent_id)</code>. Je suis certain que, si l’on demande à un développeur de récupérer toutes les catégories parentes d’une catégorie précise, ce dernier fera le traitement en PHP avec un code ressemblant au suivant:</p>\n\n<figure class=\"highlight\"><pre><code class=\"language-php\" data-lang=\"php\">// src/Repository/CategoryRepository.php\nclass CategoryRepository extends ServiceEntityRepository\n{\n    // ...\n\n    /**\n     * @return list&lt;Category&gt;\n     */\n    function getCatagoriesWithParents(int $categoryId): array\n    {\n        $category = $this-&gt;categoryRepository-&gt;find($categoryId);\n\n        $categories = [\n            $category,\n        ];\n\n        while ($parent = $category-&gt;getParent()) {\n            $categories[] = $parent;\n        }\n\n        return $categories;\n    }\n}</code></pre></figure>\n\n<p>L’inconvénient majeur ici est qu’en interne, Doctrine va faire une requête à chaque tour de boucle. C’est ce que l’on appelle <a href=\"https://www.jdecool.fr/blog/2015/12/17/le-probleme-n+1.html\">le problème N+1</a>. Pour résoudre ce problème, via une requête SQL, il n’est pas possible de faire un simple <code>SELECT ... FROM ... WHERE</code>, c’est exactement dans ce cas qu’une CTE récursive est utile. Cette dernière peut être écrite de la manière suivante:</p>\n\n<figure class=\"highlight\"><pre><code class=\"language-sql\" data-lang=\"sql\">WITH RECURSIVE cte_category AS (\n    -- point de départ\n    SELECT id, label, parent_id, 0 AS depth\n    FROM category\n    WHERE id = :id\n\n    UNION ALL\n\n    -- récursivité\n    SELECT c.id, c.label, c.parent_id, cp.depth + 1\n    FROM category c\n    INNER JOIN cte_category cp ON c.id = cp.parent_id\n)\nSELECT id, label, parent_id FROM cte_category\nORDER BY depth DESC</code></pre></figure>\n\n<p>La requête commence par récupérer la catégorie identifiée par <code>:id</code>, puis se joint récursivement à elle-même en remontant via <code>parent_id</code> jusqu’à ce qu’il n’y ait plus de parent. La colonne <code>depth</code> permet ensuite de trier du plus ancien ancêtre jusqu’à la catégorie cible.</p>\n\n<p>Le problème pour faire cette requête avec un ORM tel que Doctrine, c’est que ce dernier ne permet pas de gérer les CTE nativement au travers de son <code>QueryBuilder</code> ni même en <code>DQL</code>. Il est alors nécessaire de passer par une requête native où le résultat final sera mappé sur un objet.</p>\n\n<figure class=\"highlight\"><pre><code class=\"language-php\" data-lang=\"php\">// src/Repository/CategoryRepository.php\nclass CategoryRepository extends ServiceEntityRepository\n{\n    // ...\n\n    public function findAllWithParents(int $categoryId)\n    {\n        $rsm = new ResultSetMappingBuilder($this-&gt;getEntityManager());\n        $rsm-&gt;addRootEntityFromClassMetadata(Category::class, &#39;c&#39;);\n\n        $sql = &lt;&lt;&lt;SQL\n            WITH RECURSIVE with_categories AS (\n                SELECT id, label, parent_id, 0 AS depth\n                FROM category\n                WHERE id = :id\n\n                UNION ALL\n\n                SELECT c.id, c.label, c.parent_id, cp.depth + 1\n                FROM category c\n                INNER JOIN with_categories cp ON c.id = cp.parent_id\n            )\n            SELECT id, label, parent_id FROM with_categories\n            ORDER BY depth DESC\n        SQL;\n\n        return $this-&gt;getEntityManager()\n            -&gt;createNativeQuery($sql, $rsm)\n            -&gt;setParameter(&#39;id&#39;, $categoryId)\n            -&gt;getResult();\n    }\n}</code></pre></figure>\n\n<p>Dans le code précédent, le <code>ResultSetMappingBuilder</code> se charge de faire correspondre les colonnes retournées avec les propriétés de l’entité <code>Category</code>. On obtient alors en sortie une liste d’instances de <code>Category</code> ordonnés de la racine jusqu’à la catégorie demandée.</p>\n\n<p>Avec ce type de requête, on peut faire énormément de choses, il est par exemple, possible de récupérer tous les articles appartenant à une catégorie enfant en réutilisant la requête précédente:</p>\n\n<figure class=\"highlight\"><pre><code class=\"language-sql\" data-lang=\"sql\">WITH RECURSIVE category_path AS (\n    SELECT id, label, parent_id\n    FROM category\n    WHERE id = :id\n\n    UNION ALL\n\n    SELECT c.id, c.label, c.parent_id\n    FROM category c\n    INNER JOIN category_path cp ON c.id = cp.parent_id\n)\nSELECT a.id, a.title, a.category_id\nFROM article a\nINNER JOIN category_path cp ON a.category_id = cp.id\nORDER BY a.published_date DESC</code></pre></figure>\n\n<p>En une seule requête, on récupère tous les articles liés à la catégorie cible ou à n’importe lequel de ses ancêtres. Sans CTE récursive, il faudrait soit faire plusieurs requêtes successives pour parcourir la hiérarchie une approche bien moins efficace. Un point d’attention néanmoins, étant donné que l’on exécute une requête SQL native, il faudra faire attention à la portabilité de cette dernière, les CTE pouvant ne pas être disponible sur toutes les bases de données supportées par Doctrine.</p>\n\n<p>De plus, l’utilisation du <code>ResultSetMappingBuilder</code> nécessite que le <code>SELECT</code> de la requête contienne l’ensemble des colonnes nécessaire à l’alimentation de l’objet. À défaut, l’entité sera hydratée de manière incomplète sans qu’aucune erreur explicite ne soit levée.</p>\n",
            "summary": "J’ai déjà évoqué sur ce blog que le développement “moderne” avec les ORM masque les fonctionnalités avancées des SGBD au point que dorénavant les développeurs ne maitrisent et ne connaissent guère plus que le classique SELECT ... FROM ... WHERE .... Dans les mécanismes méconnus et qui pourtant, pourrait permettre de soulager certains traitements applicatifs, on retrouve les CTE (Common Table Expressions). Voyons comment les utiliser avec Doctrine ORM en PHP.",
            "url": "https://www.jdecool.fr/blog/2026/05/09/faire-des-requetes-cte-avec-doctrine-orm-en-php.html",
            "date_published": "2026-05-09T00:00:00+02:00",
            "tags": ["php","doctrine","orm","sql","cte"],
            "language": "fr"
        },
        
        {
            "id": "bc97a633afb778616d26cc04bb48191d",
            "title": "Simplifier vos objets immuables avec PHP 8.5",
            "content_html": "<p>PHP 8.5 a été publié le 20 novembre 2025 et, dans les nouvelles fonctionnalités proposées par cette version, on trouve notamment la possibilité de mettre à jour des propriétés lors du clonage d’objets. Une amélioration qui va permettre de simplifier nos objets immuables.</p>\n\n<!--more-->\n\n<p>En programmation orientée objet, un objet immuable est un objet dont l’état ne peut pas être modifié après sa création. Ainsi, toute “modification” visant à changer l’état de ce dernier conduit à la création d’une nouvelle instance avec les valeurs mises à jour. Cela représente un réel avantage, car leur état ne changeant jamais, les effets de bord et bugs liés à des modifications inattendues de l’objet sont ainsi limités.</p>\n\n<p>Avant PHP 8.5, la modification d’un objet immuable pouvait s’avérer fastidieuse, car il était nécessaire de créer une nouvelle instance avec les nouvelles valeurs. Cela pouvait être d’autant plus contraignant si l’objet avait de nombreuses propriétés.</p>\n\n<p>Par exemple:</p>\n\n<figure class=\"highlight\"><pre><code class=\"language-php\" data-lang=\"php\">readonly class GPSLocation\n{\n    public function __construct(\n        public float $latitude,\n        public float $longitude,\n        public float $altitude,\n        public DateTimeImmutable $timestamp,\n    ) {\n    }\n\n    public function withCoordinates(float $latitude, float $longitude): GPSLocation\n    {\n        return new GPSLocation(\n            $latitude,\n            $longitude,\n            $this-&gt;altitude,\n            $this-&gt;timestamp,\n        );\n    }\n\n    public function withAltitude(float $altitude): GPSLocation\n    {\n        return new GPSLocation(\n            $this-&gt;latitude,\n            $this-&gt;longitude,\n            $altitude,\n            $this-&gt;timestamp,\n        );\n    }\n}</code></pre></figure>\n\n<p>PHP 8.5 nous permet de simplifier cette opération en permettant de cloner l’objet tout en autorisant de mettre à jour certaines propriétés lors du clonage. Seules les propriétés devant être modifiées doivent être précisées:</p>\n\n<figure class=\"highlight\"><pre><code class=\"language-php\" data-lang=\"php\">readonly class GPSLocation\n{\n    public function __construct(\n        public float $latitude,\n        public float $longitude,\n        public float $altitude,\n        public DateTimeImmutable $timestamp,\n    ) {\n    }\n\n    public function withCoordinates(float $latitude, float $longitude): GPSLocation\n    {\n        return clone($this, [\n            &#39;latitude&#39; =&gt; $latitude,\n            &#39;longitude&#39; =&gt; $longitude,\n        ]);\n    }\n\n    public function withAltitude(float $altitude): GPSLocation\n    {\n        return clone($this, [\n            &#39;altitude&#39; =&gt; $altitude,\n        ]);\n    }\n}</code></pre></figure>\n\n",
            "summary": "PHP 8.5 a été publié le 20 novembre 2025 et, dans les nouvelles fonctionnalités proposées par cette version, on trouve notamment la possibilité de mettre à jour des propriétés lors du clonage d’objets. Une amélioration qui va permettre de simplifier nos objets immuables.",
            "url": "https://www.jdecool.fr/blog/2026/02/16/simplifier-vos-objets-immuables-avec-php-8-5.html",
            "date_published": "2026-02-16T00:00:00+01:00",
            "tags": ["php","immuable","clone"],
            "language": "fr"
        },
        
        {
            "id": "b7f980d94d8cd6ce0c4ebfd366910a0f",
            "title": "Testez votre documentation OpenAPI (avec PHP)",
            "content_html": "<p>Il n’y a rien de plus frustrant que d’utiliser une API qui ne se comporte pas de la manière qui est décrite dans sa documentation. Nombreux sont les développeurs ayant déjà vécu cette situation. Et pour cause, maintenir une documentation précise et à jour peut s’avérer être une tâche complexe et laborieuse (et ce, même si cette dernière est générée automatiquement). Pour éviter ces désagréments, il est primordial de pouvoir comparer ce qui est décrit dans la documentation avec le comportement réel du code.</p>\n\n<!--more-->\n\n<p>Dans le cadre d’une API, une partie de ce travail consiste à s’assurer de la conformité de la <a href=\"https://swagger.io/specification \" target=\"_blank\" rel=\"noopener noreferrer\">documentation OpenAPI</a>. Une solution pouvant être mise en place consiste à intégrer la validation et la vérification de la documentation au sein de tests fonctionnels. L’objectif de cette approche est de vérifier que la requête HTTP effectuée, ainsi que la réponse retournée lors du test correspondent à ce qui est spécifié. Ainsi, si les tests s’exécutent à chaque modification du code, cela permettra de garantir que l’API se comporte bien tel que décrit dans la documentation OpenAPI tout au cours de la vie du projet.</p>\n\n<p>Pour mettre en place ces tests dans un projet PHP, j’utilise généralement la bibliothèque  <a href=\"https://packagist.org/packages/league/openapi-psr7-validator \" target=\"_blank\" rel=\"noopener noreferrer\"><code>league/openapi-psr7-validator</code></a> qui permet de valider des requêtes et réponses HTTP par rapport à une spécification OpenAPI.</p>\n\n<p>Pour faciliter leur intégration dans vos bases de code, je recommande généralement d’utiliser une classe abstraitre pour mutualiser le code de vérification nécessaire et qui sera dédié aux tests de l’API. Cela pourrait ressembler au code suivant:</p>\n\n<figure class=\"highlight\"><pre><code class=\"language-php\" data-lang=\"php\">// ...\nuse Symfony\\Bundle\\FrameworkBundle\\KernelBrowser;\nuse Symfony\\Bundle\\FrameworkBundle\\Test\\WebTestCase;\n\nabstract class ApiTestCase extends WebTestCase\n{\n    protected static KernelBrowser $client;\n\n    protected function setUp(): void\n    {\n        parent::setUp();\n\n        static::$client = static::createClient();\n    }\n\n    protected function makeRequest(\n        string $method,\n        string $uri,\n        array $parameters = [],\n        array $files = [],\n        array $server = [],\n        ?string $content = null,\n        bool $changeHistory = true,\n    ): Response {\n        static::$client-&gt;request($method, $uri, $parameters, $files, $server, $content, $changeHistory);\n        $response = static::$client-&gt;getResponse();\n\n        // TODO: insérer le code de validation de la requête\n        // TODO: insérer le code de validation de la réponse\n\n        return $response;\n    }\n}</code></pre></figure>\n\n<p>Le code précédent est basé sur l’utilisation du <em>framework</em> Symfony, mais sa logique est universelle. L’idée étant d’avoir une méthode dans laquelle on puisse faire un appel HTTP, récupérer la requête HTTP effectuée ainsi que la réponse retournée afin de pouvoir effectuer des contrôles sur ces dernières.</p>\n\n<p>Ajoutons maintenant le code permettant d’effectuer la vérification des données avec la spécification OpenAPI.</p>\n\n<figure class=\"highlight\"><pre><code class=\"language-php\" data-lang=\"php\">// ...\nuse League\\OpenAPIValidation\\PSR7\\OperationAddress;\nuse League\\OpenAPIValidation\\PSR7\\ValidatorBuilder;\nuse Nyholm\\Psr7\\Request as Psr7Request;\nuse Nyholm\\Psr7\\Response as Psr7Response;\n\nabstract class ApiTestCase extends WebTestCase\n{\n    private const OPENAPI_SPECIFICATION_FILE = &#39;/path/to/specification.json&#39;;\n\n    private static ?ValidatorBuilder $validatorBuilder = null;\n\n    // ...\n\n    protected function makeRequest(\n        // ...\n        bool $enableOpenApiSpecificationRequestCheck = true,\n        bool $enableOpenApiSpecificationResponseCheck = true,\n    ): Response {\n        // ...\n\n        if ($enableOpenApiSpecificationRequestCheck) {\n            $this-&gt;validateOpenApiRequestSpecification($method, $uri, static::$client-&gt;getRequest());\n        }\n\n        if ($enableOpenApiSpecificationResponseCheck) {\n            $this-&gt;validateOpenApiResponseSpecification($method, $uri, static::$client-&gt;getResponse());\n        }\n\n        return $response;\n    }\n\n    private function validateOpenApiRequestSpecification(string $method, string $endpoint, Request $request): void\n    {\n        $validator = $this-&gt;getValidatorBuilder()-&gt;getRequestValidator();\n        $validator-&gt;validate(\n            new Psr7Request(strtolower($method), $endpoint, $request-&gt;headers-&gt;all(), $request-&gt;getContent()),\n        );\n    }\n\n    private function validateOpenApiResponseSpecification(string $method, string $endpoint, Response $response): void\n    {\n        $validator = $this-&gt;getValidatorBuilder()-&gt;getResponseValidator();\n        $validator-&gt;validate(\n            new OperationAddress($endpoint, strtolower($method)),\n            new Psr7Response($response-&gt;getStatusCode(), $response-&gt;headers-&gt;all(), (string) $response-&gt;getContent()),\n        );\n    }\n\n    private function getValidatorBuilder(): ValidatorBuilder\n    {\n        return self::$validatorBuilder ??= new ValidatorBuilder()-&gt;fromJsonFile(self::OPENAPI_SPECIFICATION_FILE);\n    }\n}</code></pre></figure>\n\n<p>De cette manière, à chaque appel à votre API, vous avez la possibilité de vérifier la documentation qui lui est associée. Vous remarquerez au passage qu’il est possible de désactiver la vérification soit de la requête soit de la réponse. Si la désactivation de la vérification de la réponse peut-être discutable, pouvoir désactiver la vérification de la requête est <strong>indispensable</strong> pour pouvoir tester les cas d’erreurs avec des appels HTTP invalides (afin de pouvoir tester le comportement d’un client qui effectuerait un mauvais appel).</p>\n\n<p>L’intégration de la validation OpenAPI dans vos tests fonctionnels vous permettra de faire “d’une pierre deux coups”: vous aurez la possibilité d’écrire des tests fonctionnels pour tester le comportement de votre code tout en permettant d’assurer sa cohérence avec votre documentation. Cette approche renforcera la qualité de votre API et évitera des désagréments auprès de vos utilisateurs.  N’hésitez pas à adapter cette méthode à votre contexte et les différents <em>frameworks</em> que vous utilisez.</p>\n",
            "summary": "Il n’y a rien de plus frustrant que d’utiliser une API qui ne se comporte pas de la manière qui est décrite dans sa documentation. Nombreux sont les développeurs ayant déjà vécu cette situation. Et pour cause, maintenir une documentation précise et à jour peut s’avérer être une tâche complexe et laborieuse (et ce, même si cette dernière est générée automatiquement). Pour éviter ces désagréments, il est primordial de pouvoir comparer ce qui est décrit dans la documentation avec le comportement réel du code.",
            "url": "https://www.jdecool.fr/blog/2025/07/28/testez-votre-documentation-openapi-avec-php.html",
            "date_published": "2025-07-28T00:00:00+02:00",
            "tags": ["tests","api","openapi"],
            "language": "fr"
        },
        
        {
            "id": "905b8a4c979b168b8e6d3e4716216340",
            "title": "Évaluez la qualité de vos tests avec les tests de mutation",
            "content_html": "<p>Très souvent, lorsque l’on souhaite mettre en place des indicateurs sur les tests d’un projet, la première mesure que l’on va mettre en place est celle de la couverture de code. Et pour beaucoup, il s’agit de la métrique principale permettant d’avoir une idée de qualité des tests d’un projet. Cette dernière sous-entend que plus la couverture est élevée et plus les tests assurent la sécurité du fonctionnement de notre code. Il s’agit pourtant d’un indicateur qui peut être trompeur.</p>\n\n<p>Il s’agit d’un <a href=\"https://www.jdecool.fr/blog/2023/01/03/a-propos-de-la-couverture-de-code.html\">sujet que j’ai déjà abordé dans ce blog</a>, expliquant que ce n’est pas parce qu’un test exécute une ligne de code que la vérification du comportement associé est efficace et pertinente. C’est dans ce cadre-là, qu’il est possible de mettre en place des tests de mutation (du <em>mutation testing</em> en anglais).</p>\n\n<!--more-->\n\n<p>Les tests de mutation introduisent volontairement des défauts dans le code source d’un projet dans le but de vérifier si les tests permettent de détecter les changements de comportement introduits. Ces “défauts” sont appelés des “mutants” (d’où le nom de tests de mutation) et correspondent à des modifications mineures du code tentant de simuler des erreurs de programmation courantes. À la suite de l’exécution de ces tests, un <strong>score de mutation</strong> est retourné. Ce dernier représente le pourcentage de mutants tués. Plus le score est élevé, plus les tests sont efficaces pour détecter les erreurs.</p>\n\n<p>Parmi les mutations les plus courantes, on retrouve:</p>\n<ul>\n  <li>le remplacement des opérateurs mathématiques: un <code>+</code> qui devient un <code>-</code>,</li>\n  <li>la modification des opérateurs de comparaison: une condition d’égalité <code>===</code> qui devient une négation <code>!==</code>,</li>\n  <li>la suppression de lignes de code,</li>\n  <li>la modification des valeurs booléennes: un <code>true</code> qui devient <code>false</code>,</li>\n  <li>la modification de valeurs de retour dans les fonctions.</li>\n</ul>\n\n<p>Les tests de mutation permettent alors d’évaluer la capacité des tests à détecter des erreurs et pas simplement à exécuter du code. Ils mettent en évidence les parties du code où les tests sont insuffisants ou inefficaces. Cela permet ainsi d’ajouter des tests aux endroits les plus pertinents. Au final, ils permettent d’améliorer la confiance envers la suite de tests.</p>\n\n<p>En PHP, l’outil le plus connu pour cela est certainement <a href=\"https://infection.github.io \" target=\"_blank\" rel=\"noopener noreferrer\">Infection</a>. Ce dernier supporte PHPUnit, PhpSpec et Codeception, nécessite PHP 7.4 au minimum avec au moins une des extensions suivantes: <code>Xdebug</code>, <code>phpdbg</code> ou <code>pcov</code> installée. Son installation est extrêmement simple, puisqu’il suffira de faire un <code>composer require --dev infection/infection</code>. Une configuration de base sera automatiquement créée au premier lancement d’Infection permettant un démarrage extrêmement rapide.</p>\n\n<p>Prenons un exemple simple pour illustrer le principe. Une classe <code>Calculator</code> qui permet d’effectuer des opérations de calcul:</p>\n\n<figure class=\"highlight\"><pre><code class=\"language-php\" data-lang=\"php\">class Calculator\n{\n    public function add(int $x, int $y): int\n    {\n        return $x + $y;\n    }\n\n    public function divide(int $x, int $y): float\n    {\n        if ($y === 0) {\n            throw new \\InvalidArgumentException(&#39;Division by zero is not allowed.&#39;);\n        }\n\n        return $x / $y;\n    }\n}</code></pre></figure>\n\n<p>Cette classe est associée aux tests suivants:</p>\n\n<figure class=\"highlight\"><pre><code class=\"language-php\" data-lang=\"php\">use PHPUnit\\Framework\\TestCase;\n\nfinal class CalculatorTest extends TestCase\n{\n    public function testAdd(): void\n    {\n        $addition = new Calculator();\n\n        $result = $addition-&gt;add(2, 3);\n\n        $this-&gt;assertEquals(5, $result);\n    }\n\n    public function testDivide(): void\n    {\n        $addition = new Calculator();\n\n        $result = $addition-&gt;divide(6, 2);\n\n        $this-&gt;assertEquals(3, $result);\n    }\n}</code></pre></figure>\n\n<p>En lançant les tests de mutation (via la commande <code>vendor/bin/infection</code>), nous obtenons le rapport suivant:</p>\n\n<figure class=\"highlight\"><pre><code class=\"language-text\" data-lang=\"text\">Metrics:\n   Mutation Score Indicator (MSI): 71%\n   Mutation Code Coverage: 85%\n   Covered Code MSI: 83%</code></pre></figure>\n\n<p>Le <code>Mutation Score Indicator</code> représente le pourcentage de mutants tués par rapport au nombre total de mutants générés. Un mutant tué correspond à au moins un test qui échoue après l’application d’un mutant. Elle constitue la métrique principale des tests de mutation. Elle qui permet de mesurer l’efficacité des tests à détecter des erreurs. Le score doit alors être le plus élevé possible.</p>\n\n<p>Le <code>Mutation Code Coverage</code> correspond au pourcentage de code parcouru par les tests de mutation. Cette métrique est similaire à la couverture de code “classique”, mais du point de vue des mutations.</p>\n\n<p>La dernière métrique, le <code>Covered code MSI</code> est un calcul effectué uniquement sur le code couvert par les tests. Elle permet notamment d’isoler l’efficacité des tests existants. Cet indicateur répond à la question: “Parmi le code que mes tests exécutent, quelle est leur efficacité à détecter des erreurs”. Cet indicateur permet de détecter si vos tests sont suffisamment présents (indicateur élevé) ou si ces derniers ne permettent pas de détecter les problèmes de manière efficace (indicateur bas).</p>\n\n<p>Pour améliorer le score des tests de mutation et par rebond la qualité de vos tests en général, il faudra <strong>tester tous les chemins d’exécution</strong> de votre code (incluant les cas limites et les exceptions). De plus, il ne faut pas se contenter de tester les cas nominaux, il est important de <strong>tester les cas d’erreurs</strong>.</p>\n\n<p>Par exemple dans les tests que nous avons écrit précédemment, nous n’avons pas testé le cas d’erreur de la division par zéro. Modifions le code précédent, pour ajouter ce dernier:</p>\n\n<figure class=\"highlight\"><pre><code class=\"language-php\" data-lang=\"php\">use PHPUnit\\Framework\\TestCase;\n\nfinal class CalculatorTest extends TestCase\n{\n    public function testAdd(): void\n    {\n        $addition = new Calculator();\n\n        $result = $addition-&gt;add(2, 3);\n\n        $this-&gt;assertEquals(5, $result);\n    }\n\n    public function testDivide(): void\n    {\n        $addition = new Calculator();\n\n        $result = $addition-&gt;divide(6, 2);\n\n        $this-&gt;assertEquals(3, $result);\n    }\n\n    public function testDivideByZero(): void\n    {\n        $addition = new Calculator();\n\n        $this-&gt;expectException(\\InvalidArgumentException::class);\n        $this-&gt;expectExceptionMessage(&#39;Division by zero is not allowed.&#39;);\n\n        $addition-&gt;divide(6, 0);\n    }\n}</code></pre></figure>\n\n<p>Nous obtenons alors le résultat ci-dessous:</p>\n\n<figure class=\"highlight\"><pre><code class=\"language-text\" data-lang=\"text\">Metrics:\n   Mutation Score Indicator (MSI): 100%\n   Mutation Code Coverage: 100%\n   Covered Code MSI: 100%</code></pre></figure>\n\n<p>Si mettre en place un calcul de la couverture de code de vos tests est un bon premier point, si vous souhaitez aller plus loin et avoir une métrique pertinente pour avoir une idée de la qualité de vos tests, les tests de mutation sont une très bonne approche. Vous aurez alors les outils pour identifier et combler les “trous” de vos tests. Et comme toute solution, il sera nécessaire de prêter attention à quelques points.</p>\n\n<p>Tout d’abord, il est important de noter que les tests de mutation sont des tests qui sont coûteux en termes de performance. La création et la mise en place de mutants sont consommatrices de ressources de calcul et de temps d’exécution. La génération de mutants peut ne pas être parfaite et peut ne pas changer le comportement observable du code. Dans ce dernier cas de figure, les mutants ne peuvent être tués, faussant ainsi le calcul final. On parle alors de “mutants équivalents”. Ces derniers entraînent alors de faux positifs, car ils ne changent pas réellement le comportement attendu.</p>\n",
            "summary": "Très souvent, lorsque l’on souhaite mettre en place des indicateurs sur les tests d’un projet, la première mesure que l’on va mettre en place est celle de la couverture de code. Et pour beaucoup, il s’agit de la métrique principale permettant d’avoir une idée de qualité des tests d’un projet. Cette dernière sous-entend que plus la couverture est élevée et plus les tests assurent la sécurité du fonctionnement de notre code. Il s’agit pourtant d’un indicateur qui peut être trompeur. Il s’agit d’un sujet que j’ai déjà abordé dans ce blog, expliquant que ce n’est pas parce qu’un test exécute une ligne de code que la vérification du comportement associé est efficace et pertinente. C’est dans ce cadre-là, qu’il est possible de mettre en place des tests de mutation (du mutation testing en anglais).",
            "url": "https://www.jdecool.fr/blog/2025/05/11/evaluez-la-qualite-de-vos-tests-avec-les-tests-de-mutation.html",
            "date_published": "2025-05-11T00:00:00+02:00",
            "tags": ["tests","phpunit","infectionphp","mutation"],
            "language": "fr"
        },
        
        {
            "id": "01edbca1795e0cbb222f920b49ea0306",
            "title": "Les constructeurs nommés comme alternative aux constructeurs multiples en PHP",
            "content_html": "<p>En PHP et, contrairement à d’autre langage, il n’est pas possible d’avoir plusieurs constructeurs dans une classe. Pouvoir définir plusieurs constructeurs peut-être intéressants dans de nombreux cas, comme par exemple, pouvoir construire un objet à partir de différents types de données. Si cela n’est pas possible en PHP, il est possible d’utiliser des <em>constructeurs nommés</em> pour avoir un fonctionnement similaire.</p>\n\n<!--more-->\n\n<p>Mais qu’est-ce qu’un constructeur nommé? Il s’agit d’une méthode statique que l’on va pouvoir appeler afin de construire une instance de classe. Ces méthodes ont l’avantage d’être potentiellement plus explicites que le constructeur de base parce qu’elles vont pouvoir ajouter une sémantique lors de la construction de notre objet.</p>\n\n<p>Prenons un premier exemple:</p>\n\n<figure class=\"highlight\"><pre><code class=\"language-php\" data-lang=\"php\">readonly class Color\n{\n    public function __construct(\n        public int $red,\n        public int $blue,\n        public int $green,\n    ) {}\n}</code></pre></figure>\n\n<p>Le code précédent définit un objet permettant de stocker une couleur. Cette dernière est composant d’un niveau de rouge, de bleu et de vert. Le constructeur principal permet ainsi de renseigner les valeurs correspondantes. Mais dans certains cas d’utilisation, nous pourrions avoir envie de créer une couleur depuis sa valeur hexadécimale. Pour cela, nous pouvons imaginer introduire un constructeur nommé <code>fromHexCode</code> pour réaliser cette tâche:</p>\n\n<figure class=\"highlight\"><pre><code class=\"language-php\" data-lang=\"php\">readonly class Color\n{\n    public static function fromHexCode(string $code): self\n    {\n        $code = ltrim($code, &#39;#&#39;);\n\n        $red = hexdec(substr($code, 0, 2));\n        $blue = hexdec(substr($code, 2, 2));\n        $green = hexdec(substr($code, 4, 2));\n\n        return new self($red, $blue, $green);\n    }\n\n    public function __construct(\n        public int $red,\n        public int $blue,\n        public int $green,\n    ) {}\n}</code></pre></figure>\n\n<p>Les utilisations de constructeur nommé sont multiples et permettent de simplifier la création d’objets, de fournir des valeurs par défaut en fonction d’un contexte d’utilisation tout en encapsulant la logique de création potentiellement complexe au sein de l’objet lui-même. Cela améliore ainsi la lisibilité et la compréhension du code.</p>\n\n<p>C’est également une technique appréciée en <em>Domain Driven Design</em> pour expliciter le processus métier qui a conduit à la création de la donnée. Prenons par exemple la création d’un utilisateur dans une application, nous pourrions imaginer la modélisation suivante:</p>\n\n<figure class=\"highlight\"><pre><code class=\"language-php\" data-lang=\"php\">class User\n{\n    public static function fromRegistration(string $name, string $email, string $password): self\n    {\n        $user = new self($name, $email, $password);\n\n        // additionnal business logic related to registration\n\n        return $user;\n    }\n\n    public static function fromSocialLogin(string $name, string $email): self\n    {\n        $user = new self($name, $email);\n\n        // additionnal business logic related to social login\n\n        return $user;\n    }\n\n    private function __construct(\n        public string $name,\n        public string $email,\n        public ?string $password = null,\n    ) {}\n}</code></pre></figure>\n\n<p>Ce dernier exemple définit une classe <code>User</code> avec un constructeur privé. Pour pouvoir créer une instance de notre objet, il sera nécessaire d’utiliser un des constructeurs nommés définis dans cette même classe. Le constructeur nommé à utiliser se fera en fonction du contexte métier dans lequel le traitement est effectué. Il y a ici un réel avantage à utiliser cette méthodologie, car elle permet de voir les éléments nécessaires à la création de notre utilisateur en fonction de l’action effectuée dans l’application.</p>\n\n<p>Car si un utilisateur se doit d’avoir un nom, un email et potentiellement un mot de passe, le code précédent rend visible le fait qu’il est obligatoire de renseigner toutes ces informations dans le cas d’un enregistrement de l’utilisateur depuis notre projet, alors que le mot de passe n’est pas nécessaire dans le cas d’une connexion d’un réseau social.</p>\n\n<p>Le concept de constructeur nommé est très puissant et peut se révéler extrêmement utile pour la maintenance et la compréhension d’une base de code. Le principe a été très brièvement introduit dans cet article et je vous recommande vivement de vous y intéresser plus en profondeur, ces derniers étant bien souvent sous-exploités.</p>\n",
            "summary": "En PHP et, contrairement à d’autre langage, il n’est pas possible d’avoir plusieurs constructeurs dans une classe. Pouvoir définir plusieurs constructeurs peut-être intéressants dans de nombreux cas, comme par exemple, pouvoir construire un objet à partir de différents types de données. Si cela n’est pas possible en PHP, il est possible d’utiliser des constructeurs nommés pour avoir un fonctionnement similaire.",
            "url": "https://www.jdecool.fr/blog/2025/01/20/les-constructeurs-nommes-comme-alternative-aux-constructeurs-multiples-en-php.html",
            "date_published": "2025-01-20T00:00:00+01:00",
            "tags": ["php"],
            "language": "fr"
        },
        
        {
            "id": "8969f283a6140599430d5b0b2ad9f1d0",
            "title": "API idempotente : définition et implémentation en PHP avec Symfony",
            "content_html": "<p>D’après la <a href=\"https://www.rfc-editor.org/rfc/rfc9110 \" target=\"_blank\" rel=\"noopener noreferrer\">RFC 9110</a> qui spécifie la sémantique d’une requête HTTP, une requête est considérée comme <em>idempotente</em> si elle peut être effectuée plusieurs fois et obtenir un résultat identique lors de chaque appel. Par exemple, si l’on tente d’accéder à une ressource REST <code>GET /resource/42</code>, deux appels à cet endpoint retourneront toujours le même résultat. Les appels <code>GET</code> à une API REST sont alors considérés comme idempotents (il en va de même pour des appels <code>PUT</code> ou <code>DELETE</code> par exemple). Mais ce n’est pas le cas d’un appel <code>POST /resource</code> qui créera alors une nouvelle ressource à chaque appel. Nous allons voir dans ce billet comment rendre un appel <code>POST</code> idempotent.</p>\n\n<!--more-->\n\n<p>Pour rendre une API idempotente, il va falloir être en mesure d’identifier de manière unique un appel à une ressource. Généralement, le client API va générer une clé unique et l’ajouter à l’appel effectué. La clé est ensuite vérifiée par le serveur pour qu’il puisse savoir si la requête reçue a déjà été traitée ou non:</p>\n\n<ul>\n  <li>Si la clé n’est pas connue, le traitement va être effectué et le résultat sauvegardé avant de retourner la réponse HTTP.</li>\n  <li>Dans le cas contraire, le serveur va retourner la réponse précédemment enregistrée.</li>\n</ul>\n\n<p>La plupart du temps, la clé d’idempotence est envoyée dans les en-têtes de l’appel HTTP afin d’éviter de polluer le corps de la requête.</p>\n\n<p>Prenons par exemple, le code source d’une API permettant de créer un billet de blog:</p>\n\n<figure class=\"highlight\"><pre><code class=\"language-php\" data-lang=\"php\">class BlogController extends AbstractController\n{\n    #[Route(&#39;/api/articles&#39;, methods: [&#39;POST&#39;])]\n    public function create(Request $request): JsonResponse\n    {\n        $post = new stdClass();\n        $post-&gt;id = Uuid::v7();\n        $post-&gt;title = $request-&gt;request-&gt;get(&#39;title&#39;, &#39;Default title&#39;);\n        $post-&gt;createdAt = new DateTimeImmutable();\n        // [...] enregistrement en base de données\n\n        return new JsonResponse($post, JsonResponse::HTTP_CREATED);\n    }\n}</code></pre></figure>\n\n<p>Comme expliqué précédemment, cette API n’est pas idempotente. Car si une même requête est effectuée deux fois de suite, un même article <code>My awesome article</code> sera ajouté en base de données.</p>\n\n<p>Nous allons maintenant ajouter à notre API la gestion d’une clé permettant de s’assurer de l’unicité du traitement d’une requête. Cette clé doit être envoyée par le client dans un en-tête que nous nommerons <code>X-Idempotent-Key</code>. Cette clé sera stockée dans un système de cache (via le composant <code>symfony/cache</code>) pendant une durée d’une heure. Si la clé n’existe pas, elle sera créée et dans le cas contraire, la réponse du traitement de la requête sera renvoyée une nouvelle fois depuis les données mises en cache.</p>\n\n<p>Cela pourrait conduire à l’implémentation suivante:</p>\n\n<figure class=\"highlight\"><pre><code class=\"language-php\" data-lang=\"php\">class BlogController extends AbstractController\n{\n    public function __construct(\n        private readonly Psr\\Cache\\CacheItemPoolInterface $cache,\n    ) {}\n\n    #[Route(&#39;/api/blog&#39;, methods: [&#39;POST&#39;])]\n    public function create(Request $request): JsonResponse\n    {\n        if (\n            // si l&#39;en-tête X-Idempotent-Key est présente\n            ($idempotentKey = $request-&gt;headers-&gt;get(&#39;X-Idempotent-Key&#39;)) !== null\n\n            // et que la donnée est en cache\n            &amp;&amp; ($postCache = $this-&gt;cache-&gt;getItem($idempotentKey))-&gt;isHit()\n        ) {\n            // on retourne la réponse présente dans le cache\n            return new JsonResponse($postCache-&gt;get(), JsonResponse::HTTP_CREATED);\n        }\n\n        // dans le cas contraire, on effectue le traitement\n\n        $post = new stdClass();\n        $post-&gt;id = Uuid::v7();\n        $post-&gt;title = $request-&gt;request-&gt;get(&#39;title&#39;, &#39;Default title&#39;);\n        $post-&gt;createdAt = new DateTimeImmutable();\n        // [...] enregistrement en base de données\n\n        // dans le cas où la clé d&#39;idempotence est définie\n        if ($idempotentKey !== null) {\n            // on enregistre le résultat du traitement en cache\n            $item = $this-&gt;cache-&gt;getItem($idempotentKey);\n            $item-&gt;set($post);\n            $item-&gt;expiresAfter(3600);\n            $this-&gt;cache-&gt;save($item);\n        }\n\n        return new JsonResponse($post, JsonResponse::HTTP_CREATED);\n    }\n}</code></pre></figure>\n\n<p>De cette manière notre API pourra être idempotente, améliorant ainsi sa fiabilité ainsi que la cohérence des données du service. L’idempotence permet de garantir que les requêtes identiques produisent toujours le même résultat, évitant ainsi les doublons involontaires qui pourraient survenir en cas de problème réseau par exemple.</p>\n\n<p>Faut-il mettre en place ce mécanisme partout ? Pas nécessairement. Focalisez-vous sur les opérations les plus critiques de votre système et en particulier les opérations de modification de l’état de ce dernier.</p>\n",
            "summary": "D’après la RFC 9110 qui spécifie la sémantique d’une requête HTTP, une requête est considérée comme idempotente si elle peut être effectuée plusieurs fois et obtenir un résultat identique lors de chaque appel. Par exemple, si l’on tente d’accéder à une ressource REST GET /resource/42, deux appels à cet endpoint retourneront toujours le même résultat. Les appels GET à une API REST sont alors considérés comme idempotents (il en va de même pour des appels PUT ou DELETE par exemple). Mais ce n’est pas le cas d’un appel POST /resource qui créera alors une nouvelle ressource à chaque appel. Nous allons voir dans ce billet comment rendre un appel POST idempotent.",
            "url": "https://www.jdecool.fr/blog/2025/01/13/ecrire-une-api-idempotente-en-php-avec-symfony.html",
            "date_published": "2025-01-13T00:00:00+01:00",
            "tags": ["api","php","symfony","idempotence"],
            "language": "fr"
        },
        
        {
            "id": "9a1f733df51ec147566abd22976c4b5b",
            "title": "Le pattern Optional, le conteneur de valeur qui va remplacer vos données nullables",
            "content_html": "<p>Nous manipulons tous au quotidien des données <em>nullables</em>, or manipuler des données qui peuvent être <code>null</code> implique de devoir effectuer de nombreuses vérifications afin de savoir si la donnée que l’on manipule contient bien une valeur avant de l’utiliser. Auquel cas, nous aurons une erreur de type:</p>\n\n<pre><code class=\"language-text\">PHP Warning:  Uncaught Error: Call to a member function method() on null in php shell code:1\nStack trace:\n#0 {main}\n  thrown in php shell code on line 1\n</code></pre>\n\n<p>Pour éviter l’utilisation de conditions de type <code>if ($var !== null)</code>, il est possible d’utiliser le <em>pattern</em> <code>Optional</code> qui peut s’apparenter à la monade <code>Maybe</code>.</p>\n\n<!--more-->\n\n<p>Un <code>Optional</code> est un conteneur permettant d’encapsuler une valeur qui peut être présente ou non. Ainsi, plutôt que d’utiliser une variable <code>null</code> pour représenter une valeur absente, nous allons pouvoir manipuler systématiquement un objet et appeler des méthodes sur ce dernier qui effectuera des opérations en fonction que la valeur soit présente ou non.</p>\n\n<p>Prenons un exemple concret pour illustrer ce concept. Sur un site d’e-commerce, un événement est émis une fois un achat effectué par un utilisateur afin de lui envoyer un récapitulatif de sa commande. La gestion de l’envoi de l’email pourrait ressembler au code suivant:</p>\n\n<figure class=\"highlight\"><pre><code class=\"language-php\" data-lang=\"php\">class Customer\n{\n    public ?string $email;\n}\n\nreadonly class OrderConfirmed\n{\n    public Customer $customer;\n}\n\nreadonly class OrderNotification\n{\n    public function __construct(private EmailSender $email) {}\n\n    public function sendConfirmatinEmailOnOrderConfirmed(OrderConfirmed $event): void\n    {\n        if ($event-&gt;getCustomer() == null) { // invite account\n            return;\n        }\n\n\n        if ($event-&gt;getCustomer()-&gt;getEmail() == null) { // no email filled\n            return;\n        }\n\n        $this-&gt;email-&gt;send($event-&gt;getCustomer()-&gt;getEmail(), &#39;Email content&#39;);\n    }\n}</code></pre></figure>\n\n<p>Nous voyons dans ce cas d’exemple, qu’il est nécessaire de faire deux vérifications avant de pouvoir envoyer notre e-mail de confirmation:</p>\n\n<ol>\n  <li>Dans un premier temps, il est nécessaire de vérifier que la commande n’a pas été effectuée en “mode invité”, ce qui impliquerait d’avoir une commande sans notion d’acheteur,</li>\n  <li>Il est ensuite nécessaire de vérifier que l’on a bien une adresse de renseignée pour pouvoir envoyer l’e-mail.</li>\n</ol>\n\n<p>Voyons maintenant ce que pourrait donner ce même code avec l’utilisation du pattern <code>Optional</code>:</p>\n\n<figure class=\"highlight\"><pre><code class=\"language-php\" data-lang=\"php\">class Customer\n{\n    /** @var Optional&lt;string&gt; */\n    public Optional $email;\n}\n\nreadonly class OrderConfirmed\n{\n    /** @var Optional&lt;Customer&gt; */\n    public Optional $customer;\n}\n\nreadonly class OrderNotification\n{\n    public function __construct(private EmailSender $email) {}\n\n    public function sendConfirmatinEmailOnOrderConfirmed(OrderConfirmed $event): void\n    {\n        $event-&gt;customer\n            -&gt;flatMap(static fn (Customer $customer) =&gt; $customer-&gt;email)\n            -&gt;ifPresent(static fn (string $email) =&gt; $this-&gt;email-&gt;send($event-&gt;getCustomer()-&gt;getEmail(), &#39;Email content&#39;));\n    }\n}</code></pre></figure>\n\n<p>Dans cette seconde version, nous constatons que toutes nos vérifications (les <code>if</code>) ont été supprimées. Le code s’en retrouve plus concis et surtout se concentre sur les opérations utiles au traitement de l’envoi de notre e-mail, ce qui le rend plus expressif. Il n’est plus question de devoir vérifier si la donnée est présente ou non, la structure de données <code>Optional</code> va appliquer les transformations demandées uniquement si la valeur est présente et ne fait rien dans le cas contraire.</p>\n\n<p>Les monades gagnant en popularité ces dernières années, on commence à voir des implémentations du pattern <code>Optional</code> directement dans les langages de programmation. Ce n’est (malheureusement) pas le cas en PHP. Mais on retrouve quelques implémentations sur <a href=\"https://packagist.org \" target=\"_blank\" rel=\"noopener noreferrer\">Packagist</a>.</p>\n\n<p>Bien que son utilisation dans l’écosystème PHP reste marginale, à la vue des nombreux avantages qu’il représente, vous avez tout intérêt à regarder ça de plus près. Pour ma part, j’ai commencé à introduire cette notion en construisant ma propre implémentation qui se résume à quelques lignes de code.</p>\n",
            "summary": "Nous manipulons tous au quotidien des données nullables, or manipuler des données qui peuvent être null implique de devoir effectuer de nombreuses vérifications afin de savoir si la donnée que l’on manipule contient bien une valeur avant de l’utiliser. Auquel cas, nous aurons une erreur de type… Pour éviter l’utilisation de conditions de type if ($var !== null), il est possible d’utiliser le pattern Optional qui peut s’apparenter à la monade Maybe.",
            "url": "https://www.jdecool.fr/blog/2024/10/25/le-pattern-optional-le-conteneur-de-valeur-qui-va-remplacer-vos-donnees-nullables.html",
            "date_published": "2024-10-25T00:00:00+02:00",
            "tags": ["php","optional","pattern"],
            "language": "fr"
        },
        
        {
            "id": "f8b0af131d0d343fa6839f646db6a97b",
            "title": "Installer des extensions PHP facilement dans une image Docker",
            "content_html": "<p>Si vous avez déjà construit des images Docker pour des applications ou projet PHP, vous avez certainement utilisé l’outil <code>docker-php-ext-install</code>. Ce dernier permet d’installer et configurer simplement des extensions PHP qui seront disponibles dans le conteneur. Néanmoins, cet outil se limite malheureusement aux extensions officielles fournies avec le langage.</p>\n\n<!--more-->\n\n<p>Pour résoudre ce problème et permettre d’installer de nombreuses extensions PHP dans un conteneur Docker, il existe un outil disponible librement sur Github: <a href=\"https://github.com/mlocati/docker-php-extension-installer \" target=\"_blank\" rel=\"noopener noreferrer\"><code>mlocati/docker-php-extension-installer</code></a>. Ce dernier met à disposition un script nommé <code>install-php-extensions</code> qui vous permettra d’installer et de configurer des extensions PHP au sein de votre image. À la différence du script officiel, il ne se limite pas aux seules extensions fournies directement avec PHP puisqu’il couvre un très large panel d’extensions parmi lesquelles: <code>amqp</code>, <code>cassandra</code>, <code>ioncube_loader</code>, <code>jsonpath</code>, <code>newrelic</code>, <code>rdkafka</code>, <code>xdebug</code> et bien d’autres encore.</p>\n\n<p>Mais il permet d’aller encore plus loin en installer également les dépendances nécessaires à l’installation des extensions. Il installera par exemple la bibliothèque <code>rabbitmq-c</code> nécessaire au bon fonctionnement de l’extension <code>amqp</code> permettant entre autres de communiquer avec RabbitMQ.</p>\n\n<p>Fonctionnant avec les images basées sur Debian et Alpine, vous aurez la possibilité d’installer les extensions pour les versions de 7.1 à 8.4 de PHP, de quoi couvrir un grand nombre de besoins et cas d’utilisation.</p>\n\n<p>Et pour finir, voici un exemple d’utilisation:</p>\n\n<figure class=\"highlight\"><pre><code class=\"language-dockerfile\" data-lang=\"dockerfile\">FROM php:8.3-cli\n\nADD --chmod=0755 https://github.com/mlocati/docker-php-extension-installer/releases/latest/download/install-php-extensions /usr/local/bin/\n\nRUN install-php-extensions amqp gd xdebug</code></pre></figure>\n\n<p>Si vous êtes passé à côté de cet outil et que vous utilisez encore une combinaison des utilitaires officiels et/ou <code>pecl</code>, je ne peux que vous encourager à tester cet outil.</p>\n",
            "summary": "Si vous avez déjà construit des images Docker pour des applications ou projet PHP, vous avez certainement utilisé l’outil docker-php-ext-install. Ce dernier permet d’installer et configurer simplement des extensions PHP qui seront disponibles dans le conteneur. Néanmoins, cet outil se limite malheureusement aux extensions officielles fournies avec le langage.",
            "url": "https://www.jdecool.fr/blog/2024/10/23/installer-des-extensions-php-facilement-dans-une-image-docker.html",
            "date_published": "2024-10-23T00:00:00+02:00",
            "tags": ["php","docker","extensions php"],
            "language": "fr"
        }
        
    ]
}
