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

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

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

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

Section intitulée l-aventure-d-une-requete-http-ou-le-chemin-de-la-vie-des-devsL’aventure d’une requête HTTP — ou le chemin de la vie des devs

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

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

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

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

Sketch de la conférence par Mathieu Desnouveaux.

Section intitulée creer-des-interfaces-d-administration-rapidement-avec-symfony-ux-et-syliusCréer des interfaces d’administration rapidement avec Symfony UX et Sylius

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

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

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

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

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

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

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

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

Section intitulée utiliser-une-faille-glibc-pour-attaquer-le-moteur-phpUtiliser une faille glibc pour attaquer le moteur PHP

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

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

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

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

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

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

Essayons de résumer le cheminement :

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

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

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

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

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

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

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

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

Section intitulée les-objets-paresseux-en-phpLes objets paresseux en PHP

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

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

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

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

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

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

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

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

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

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

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

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

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

Section intitulée optimiser-les-performances-de-votre-api-avec-automapperOptimiser les performances de votre API avec AutoMapper

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

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

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

Section intitulée configurationConfiguration

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

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

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

Section intitulée utilisationUtilisation

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

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

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

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

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

    // ...

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

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

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

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

Section intitulée l-oriente-objet-au-coeur-du-templating-symfony-decouvrez-twigcomponent-et-livecomponentL’Orienté Objet au Cœur du Templating Symfony : Découvrez TwigComponent et LiveComponent

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

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

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

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

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

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

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

<Twig:Component :prop="prop">

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

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

Section intitulée ecrire-du-php-avec-seulement-6-caracteresÉcrire du PHP avec seulement 6 caractères

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

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

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

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

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

Section intitulée webhooks-at-scaleWebhooks at scale

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

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

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

Section intitulée fail-fast-policyFail fast policy

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

Section intitulée circuit-breakerCircuit breaker

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

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

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

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

Section intitulée covariance-contravariance-et-diamantCovariance, Contravariance et Diamant

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

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

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

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

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

Section intitulée decouverte-de-castor-le-task-runner-php-qui-simplifie-votre-workflowDécouverte de Castor : Le Task Runner PHP qui Simplifie votre Workflow

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

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

Section intitulée dis-siri-mets-des-elephpants-dans-ma-domotiqueDis Siri, mets des éléPHPants dans ma domotique

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

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

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

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

Section intitulée le-zero-downtime-deployment-en-pratiqueLe Zéro Downtime Deployment en pratique

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

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

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

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

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

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

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

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

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

Section intitulée wordpress-une-cause-perdueWordPress : une cause perdue ?

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

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

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

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

Il nous a montré qu’on pouvait :

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

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

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

Section intitulée utiliser-un-framework-pour-ecrire-de-la-documentationUtiliser un framework pour écrire de la documentation ? 📖

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

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

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

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

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

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

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

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

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

Pro Tip © : dans Notion on peut donner une date de validité à un document !

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

Section intitulée merci-l-afupMerci l’AFUP

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

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

---

Cet article porte sur la conférence Forum PHP 2024.