Pourquoi et comment lire le code de WordPress

Cet article est la retranscription d’une conférence que j’ai eu la chance d’animer au WordCamp Paris 2016.
Encore bravo aux organisateurs, au passage, qui se sont vraiment investis pour faire de cette édition une réussite !

Bravos aux organisateurs qui ont faits un travail remarquable pour cette édition ! (photo par Olivier Gobet)

Comme de nombreuses personnes dans la communauté de WordPress, je n’ai pas fait de formation de développeur. Après le bac j’ai suivi pendant 5 ans un cursus d’arts plastiques.

C’est au cours de mes études, par affinité et pour explorer le potentiel artistique du web que je me suis mis à « coder ». J’ai tellement aimé ça que j’ai stoppé net les études et que je me suis décidé à en faire mon métier.

Je me suis donc formé tout seul, à l’intégration d’abord, puis au javascript et au PHP. Bon, le PHP c’est très sympa mais faire un site from scratch, administration comprise, pour un débutant ça me paraissait être un peu trop complexe. C’est pour cette raison que j’ai testé quelques CMS avant de me tourner définitivement vers WordPress.

J’ai donc continué mon apprentissage grâce aux ressources que j’avais sous la main : principalement les blogs francophones (merci énormément à eux), et puis le codex, qui – certes moins complet à l’époque – était déjà une bonne ressource lorsqu’il s’agissait de comprendre une fonction ou une API.

Mais voilà, à un certain moment, on ne trouve plus de tutoriel pour développer des fonctionnalités plus avancées. Et c’est là que l’on en arrive au sujet de ma conférence : pour comprendre comment fonctionne WordPress, et pour savoir comment l’utiliser, comment le personnaliser, rien ne m’a autant aidé que de lire le code source.

Pourquoi prendre du temps pour lire le code ?

Oui, après-tout, pourquoi ne nous en passerions pas ?

Lorsque l’on veut construire un thème, un plugin, utiliser l’API REST, il y a maintenant davantage de ressources pour nous expliquer comment s’y prendre. Quand je vous parle de mon apprentissage, c’était il y a 8 ans, il n’y avait pas de slack, moins de groupe Facebook, moins d’événements… Alors que maintenant il y a plus des ressources – et en français notamment – qui vont vous expliquer tout ça dans un langage vulgarisé :

Le problème, c’est que si vous ne vous reposer que là-dessus, vous n’aurez accès qu’à des interprétations du code.

Les gens vous donnerons des solutions, ils vous expliqueront à quoi sert telle ou telle fonction, et tel ou tel hook si vous le leur demandez, dans les grandes lignes…
Alors qu’en lisant le code source, vous verrez chaque ligne de code dans son contexte : là où elle est utilisée, comment elle est définie, ce qui se passe avant et ce qui se passe ensuite.

Pour chaque fonction par exemple, vous connaitrez ces paramètres, la nature de l’élément sur laquelle elle agit, et les filtres qui viennent avant et après…

Avec un peu d’habitude et une bonne façon de faire, lire la source va nous permettre de progresser et de devenir de meilleurs développeurs, de meilleurs intégrateurs, de meilleurs architectes.

Vous allez découvrir des fonctions utiles

Assez rapidement ce qui va vous faire progresser c’est, qu’à parcourir le code, vous allez découvrir des fonctions et des hooks qui vous seront utiles. Du coup vous chercherez moins à « réinventer la roue ». Pour adapter certaines fonctionnalités, avant de sentir la nécessité d’installer un plugin, vous connaitrez peut-être des filtres, actions ou fonctions que vous pourrez utiliser pour parvenir à vos fins plus simplement. Votre code sera également plus « natif » et donc plus stable au fil des mises à jour de WordPress.

Et puis à force, vous finirez par avoir une meilleure vue d’ensemble du fonctionnement de WordPress. Vous saurez comment intervenir pour ne pas créer de bug, et vous aurez aussi des petites pistes pour corriger les problèmes que vous rencontrez.

Il faut connaître les bases de la programmation

Attention, je ne parle pas ici de savoir écrire du code, ni de maitriser un langage précis. Il est juste nécessaire de connaitre des structures/éléments que l’on retrouve dans la plupart des langages informatiques :

Avec ces bases, vous aurez tout ce qu’il faut pour suivre ce que fait WordPress au fil des différents fichiers. Et puis rassurez-vous…

Le code est très bien commenté

L’ensemble des fichiers PHP du code source (et une bonne partie des fichiers javascript) est commenté. C’est-à-dire qu’avant chaque fonction, un bloc de commentaire indique :

Cette documentation est très complète, mais pas 100% exhaustive. Par exemple elle n’indique pas si une fonction qu’elle appelle utilise un hook (get_option embarque deux hooks, pareil pour les fonctions de traduction ou les Walkers), ou bien elle n’indique pas les filtres de la classe parente…

C’est néanmoins cette documentation qui est extraite du core et reprise sur différents sites tels que le « Developer Reference », « WP Hooks Database », « Queryposts », « WP Seek »…

L’arborescence de WordPress

Avant de se jeter à core perdu dans le code, faisons un petit tour du propriétaire !

À la racine

Au rez de chaussé, on trouve deux types de fichiers :

Les répertoires

Le reste des fichiers de WordPress sont repartis dans 3 dossiers principalement :

Donc pour résumer : les fichiers qui vont vous apprendre des choses sont principalement ceux que vous trouverez dans wp-includes et à la racine. Ceux qui sont dans wp-admin ne vous serviront que si vous vous intéressés à l’administration de WordPress (par exemple si vous souhaitez concevoir une UI pour un plugin).

Maintenant que vous avez une vue d’ensemble de l’arborescence du code, je vais vous indiquez comment l’explorer afin de découvrir des choses passionnantes.

La mauvaise façon de faire

L’idée vous a peut-être déjà effleuré l’esprit de lire le code de WordPress par le début ; j’entends par là « en lisant ce qui se passe à partir d’index.php ». Voici ce qui se passe alors :

index
Index.php appelle wp-blog-header…
wp-blog-header
… qui appelle wp-load …
wp-load
… qui charge wp-config …
wp-config
… qui appelle wp-settings.php

Et c’est là que ça devient chaud… puisque wp-settings.php va charger beaucoup de fichiers en même temps !

wp-settings
Si vous voulez continuer à suivre, bon courage !

C’est pour ça que cela n’est pas la bonne approche. À moins que votre souhait est de comprendre le chargement du core, il vous faudra procéder autrement.

S’intéresser aux fichiers en lien avec votre projet

WordPress est une grosse machine constitué de plus de 1500 fichiers. Ceux-ci s’articulent en petits groupes qui gèrent chacun une fonctionnalité du CMS (on parle d’ailleurs d’API dans certains cas : l’api settings, l’api transient, l’api heartbeat, l’api customizer…).

Si vous essayez de lire le code sans avoir d’objectif, vous n’allez pas savoir par quel bout le prendre.

Alors que si vous êtes sur un projet, vous pouvez vous dire : « Tiens, comment ça marche ça ? », rentrer dans le code à cet endroit et vous promener dans le code par la suite. Donc plutôt que de courir sur slack demander de l’aide ou « quel plugin installer » dès que vous rencontrer un obstacle, prenez le temps de lire le code… Au fil des fichiers que vous lirez, vous finirez par avoir une connaissance globale du fonctionnement du CMS.

Une méthode pour trouver les fichiers qui vous intéressent

Mais comment faire alors pour trouver les fichiers qui correspondent aux fonctions que vous employez ?

Pour cela il va nous falloir posséder une version de WordPress sur notre ordinateur. Sois en téléchargeant une archive sur WordPress.org, soit en faisant un checkout (ou un clone) du dépôt svn (ou git) officiel.

Ensuite nous allons utiliser la fonction « find in files » (cmd + shift + f) d’un éditeur de texte pour rechercher des motifs de code, et se rendre dans les fichiers où ils se trouvent.

Par exemple, mettons que nous travaillons sur un template, et qu’on se pose la question : « à quoi ressemble la fonction the_excerpt() ? ». Il suffit alors de rechercher the_excerpt dans tous les fichiers de WordPress.

Enfin presque…

En faisant ceci, vous récupérerez non seulement la déclaration de la fonction, mais également tous les fichiers où elle est utilisée, ainsi que les filtres de cette fonction…

Une meilleure façon de faire est de rechercher uniquement function the_excerpt(.

L’éditeur vous renverra alors uniquement la déclaration de fonction, et vous pourrez lire le code, la documentation en ligne, voir les filtres utilisé et les fonctions en lien. Ici on s’aperçoit qu’un filtre est disponible. Si vous souhaitez savoir si le cœur de WordPress applique des filtres sur ce hook, il faut rechercher add_filter( 'the_content'.

Et voilà, ici on s’aperçoit que dans le fichier default-filters.php, WordPress applique 4 filtres de nettoyage sur ce hook.

Il est également possible de rechercher des hooks d’action. Par exemple imaginons que vous souhaitez désactiver les notifications de commentaire, et que vous savez que la fonction qui s’occupe de l’ajout de commentaire est wp_new_comment(). Il faut alors vous rendre dans cette fonction, rechercher le nom de l’action appliquée, puis faire une recherche sur le terme add_action( 'comment_post' dans les fichiers de WordPress. Vous pourrez ensuite supprimer l’action appliquée par le biais d’un remove_action().

Toujours dans vos template, si vous souhaitez en savoir davantage sur une classe, telle que WP_Query. Le motif à rechercher est class WP_Query (avec un espace après, comme indiqué dans les coding standards). Vous allez trouver la classe, il faudra ensuite rechercher dans cette class la fonction __construct() dont le rôle est d’instancier l’objet, pour savoir par où commencer la lecture.

Au passage : WP_Query est une classe particulièrement intéressante à lire !

Maintenant il est possible que certaines classes hérite d’une classes parente. Il faut donc penser à aller voir celle-ci pour comprendre le fonctionnement d’une classe dans son ensemble. C’est par exemple le cas pour Walker_Nav_menu qui hérite de classe abstraite Walker.

Avec ces motifs, il vous est maintenant possible de trouver des points d’entrées pour lire du code intéressant lorsque vous faites du theming.

Lire le code de l’administration

Pour trouver les fichiers intéressants de l’administration, il va falloir adapter notre technique, puisqu’en back-office vous ne connaissez pas le nom des fonctions utilisées.

En revanche, il se trouve que le marquage HTML est fait de façon moins dynamique. Vous pouvez donc vous y fier davantage pour retrouver certains fichiers. Je recommande de parcourir le DOM pour trouver des classes ou id qui vous semblent génériques afin de les rechercher dans les fichiers.

Par exemple si vous souhaitez savoir quelle fonction compose les listes d’articles, pages, plugins, utilisateurs, il faut examiner cet élément. On voit qu’une classe css wp-list-table semble générique à cet élément.

Une recherche dans les fichiers nous renverra rapidement vers la classe WP_List_Table dans class-wp-list-table.php.

Dans l’admin, contrairement au front-office, le cœur de WordPress utilise du javascript pour déclencher certaines actions de l’interface. Ces fonctions pourraient vous être utiles dans vos développements de plugin, par exemple si vous souhaitez concevoir une interface.

Faire une recherche de code dans le JS se fait en deux étapes :

  1. Définir la constante SCRIPT_DEBUG à true, dans wp-config.php, afin que le code JS ne soit plus minifié ;
  2. Utiliser l’inspecteur du navigateur pour analyser les écouteurs d’événements des éléments de l’UI qui déclenches des fonctions javascript.

Voici un exemple avec le bouton d’édition du permalien d’un article.

Que faire lorsque l’on ne trouve pas de résultat ?

Il peut arriver que vos recherches ne renvoient aucun résultat. C’est que vous être en train de rechercher quelque chose qui ne dépend pas du cœur de WordPress mais d’un autre élément. Ce peut être :

Je précise donc que, bien sûr, les techniques que j’ai présenté ici servent pour rentrer dans le cœur de WordPress mais aussi pour découvrir le fonctionnement des plugins que vous utilisez fréquemment.

Par exemple il peut-être très intéressant de fouiller le fonctionnement d’extensions aussi complexes que Woocommerce, pour débugger vos développements, mais aussi pour savoir comment écrire du code qui sera compatible au fil des mises à jour.

Quelques fichiers intéressants

Je le répète : le mieux pour comprendre le code de WordPress est de s’intéresser aux fichiers en rapport avec un de vos projets en cours. Cependant si vous avez trop hâte de plonger dans le bain, que vous avez envie de lire des fichiers particulièrement intéressants, en voici quelques-uns :

  1. wp-includes/formatting.php et wp-includes/default-filters.php
    Le premier fichier contient les fonctions de nettoyage et de vérifications de chaines. Le second applique ces fonctions via des filtres sur de nombreux éléments de WordPress
  2. wp-includes/functions.php
    C’est un peu le « tout-venant » des fonctions super utiles de WordPress
  3. wp-includes/query.php
    J’en ai déjà brièvement parlé, c’est le fichier qui contient la class WP_Query. En lisant ce fichier vous trouver pleins de méthodes pour personnaliser le chargement des contenus dans la boucle
  4. wp-includes/class-wp.php
    Si vous souhaitez comprendre comment « démarre » WordPress du parse_request au query_vars en passant par les routes
  5. wp-includes/general-template.php et wp-includes/post-template.php
    Ces deux fichiers vous permettront de comprendre ce que font les fonctions que vous utiliser partout dans vos templates ;-)

Ça fait déjà une bonne pile de choses à lire !
Vous avez maintenant toutes les cartes en main pour lire le code et progresser.

Suite à ma conférence et à différents retours, je tiens tout de même à insister sur un point : lire la documentation ne suffit pas. En effet la doc n’est pas exhaustive, aucune ne l’est… connaître les paramètres ou les filtres principaux d’une fonction ne suffit pas pour savoir comment ça marche. Par exemple les commentaires ne mentionneront pas systématiquement si un walker est employé, ils ne vous indiqueront pas non plus que derrière chaque get_option(), chaque __() ou chaque shortcode_atts() se cachent plusieurs filtres…

Et puis c’est beau le code non ?

Épilogue : code is poetry

J’ai hésité à en parler dans cette conférence, mas ça faisait un peu beaucoup, alors je préfère parler de cela sur ce blog, en épilogue, surtout que c’est une réflexion que l’on peut dissocier du reste.

Code is Poetry (le code est une poésie) est la tagline, la devise de WordPress…

Ce n’est pas une phrase qu’il faut prendre au premier degré, cela ne sert à rien bien sûr d’ouvrir un fichier PHP, de s’éclaircir la voix et de lire le code en alexandrins… il n’y aura pas de rythme, pas de rime… pas très intéressant tout ça… le code ne pourra pas vous faire ressentir d’émotions (à part un peu d’humour, parfois…).

Le sens que l’on peut trouver à cette phrase, c’est qu’on peut percevoir une similarité importante entre le code et la poésie : chaque élément à un sens, une raison d’être là – chaque fichier, chaque fonction, chaque filtre, chaque point-virgule. Et c’est particulièrement le cas pour un code avec autant de vécu que celui de WordPress.

WordPress a plus de 11 ans maintenant, et son code est encore plus ancien. Il a été forgé par des milliers de contributeurs, chacun venant solidifier l’édifice au fil des ans, l’enrichir pour arriver a ce qu’il est aujourd’hui : un merveilleux « objet de langage »

Un objet dont la matière qui le constitue est « des fichiers », 1513 fichiers et de millions de « mots » dont l’agencement nous parait optimal (en termes de rapport performance/compatibilité/fonctionnalités). Et la preuve c’est que lorsque l’on suggère de bouger deux lignes de codes il faut quand même assez d’énergie pour arriver à convaincre les core-commitors.

Bref, lire le code ne vous procurera pas beaucoup d’émotions, mais peut-être un sentiment de satisfaction en comprenant comment toutes ces lignes de code sont élégamment agencées pour constituer cet objet qu’est WordPress.

Contacter l'auteur :

willy bahuaud

Je suis Willy Bahuaud, développeur de sites et plugins WordPress. Je suis également co-organisateur du WP Tech, le seul événement exclusivement technique consacré à WordPress en France. Passionné de code, les événements organisés par la communauté sont l'occasion de pouvoir échanger avec les utilisateurs et développeurs de WordPress.
Vous souhaitez des informations ? Écrivez-moi

9 commentaires

  1. Par Karine — Il y a 10 mois
    Article tout simplement remarquable ! !!!! Direct dans mes favoris. Mille mercis.
  2. Par Rashel — Il y a 10 mois
    Conférence super intéressante, et un recap parfait ! Merci Willy !
  3. Par Laetitia Modine — Il y a 10 mois
    Excellent article ! Merci d’avoir partagé votre expertise et votre retour d’expérience 🙂
  4. Par Maximebj — Il y a 10 mois
    Super intéressant Merci 🙂 très belle conclusion ! Je vais me lire une bonne 800aine de lignes et je verrais si je continue ;)
  5. Par Victor Geek — Il y a 6 mois
    Cet article fait voir WordPress d’un autre angle. Voilà des articles qui font avancer les choses ! 🙂 Merci
  6. Par Resolution Web — Il y a 6 mois
    Bonjour,
    Tiens je dois être le seul à dire bonjour, je dois être « Has been ».
    Je me met tout doucement au dev de module sur WordPress et ton ébauche est plutôt sympa pour gagner du temps, c’est vrai que j’aurai eu tendance à commencer par lire le « Core »…
    Sinon j’ai une astuce que j’utilise pour chercher une class ou un morceau de code en faisant une recherche dans le github, je ne sais pas si c’est très académique.
    Je découvre ton blog depuis WordPress-fr et whouah il est magnifique, j’ai honte du mien que je dois vite refaire ;)
  7. Par Benjamin — Il y a 5 mois
    Code is poetry. Voilà comment tout résumer en une phrase ;) J’aime bien ce principe. Car la poésie, ce n’est pas seulement de la rhétorique, il y a une structure, une syntaxe particulière à respecter, une mise en forme, …
    Enfin en tout cas bel article ;)
  8. Par Eric — Il y a 2 mois
    Wow ! Ca c’est ce que l’on appelle un article documenté !
    Merci pour toutes les infos et les vidéos.
  9. Par juan — Il y a 1 semaine
    Salut !

    Super article ! bravo et merci.

    Et super site ;)

Commenter