Personnaliser wp-env avec un service MySQL 8 différent du réglage par défaut

wp-env start monte en quelques secondes un environnement WordPress complet avec Docker, mais avec une contrainte pour qui contribue au cœur du logiciel : la version de MySQL utilisée par défaut ne correspond pas toujours à celle de l’hébergeur où un bug a été signalé. Reproduire fidèlement ce bug suppose de changer cette version, sans renoncer au confort de wp-env pour le reste de l’environnement.

Le cas concret : un rapport de bug touchant une requête impliquant une contrainte de clé étrangère, reproductible uniquement sur MySQL 8 et absent sur la version fournie par défaut. Plutôt que de monter un environnement Docker entièrement manuel, la solution la plus rapide a consisté à surcharger la configuration générée par wp-env pour son propre service de base de données.

Comprendre ce que wp-env génère par défaut

wp-env repose sur un fichier .wp-env.json à la racine du projet, qui définit les extensions et thèmes chargés, la version de PHP, et divers réglages de configuration WordPress via la clé config. En interne, l’outil génère automatiquement un fichier docker-compose.yml à partir de ces réglages, avec un service mysql basé sur une image MySQL par défaut, sans que ce choix de version soit directement exposé dans .wp-env.json.

{
  "core": null,
  "phpVersion": "7.4",
  "plugins": [ "." ],
  "config": {
    "WP_DEBUG": true
  }
}

Localiser le fichier docker-compose généré

La commande wp-env start place les fichiers générés dans un dossier temporaire propre à chaque projet, habituellement sous ~/.wp-env/, identifié par un hash calculé à partir du chemin du projet. C’est dans ce dossier que se trouve le docker-compose.yml réellement utilisé, avec la définition complète du service mysql et l’image utilisée par défaut.

wp-env start
docker ps --filter "name=mysql"
docker inspect <id_conteneur_mysql> --format='{{.Config.Image}}'

Surcharger le service sans casser wp-env

Modifier directement le fichier généré ne survivrait pas à un wp-env destroy suivi d’un nouveau wp-env start, qui régénère systématiquement la configuration. La solution durable consiste à arrêter l’environnement, puis à relancer manuellement les conteneurs avec Docker Compose en pointant sur une variante du fichier généré où l’image du service mysql a été remplacée par mysql:8.0, tout en conservant les réseaux et volumes créés par wp-env pour que WordPress continue de s’y connecter normalement.

1. Lancer une première fois wp-env start pour générer la configuration complète
2. Copier le docker-compose.yml généré vers un fichier de travail versionné dans le projet
3. Remplacer la ligne d’image du service mysql par mysql:8.0
4. Arrêter les conteneurs wp-env puis relancer avec ce fichier modifié via docker compose -f mon-docker-compose.yml up

Vérifier que le bug se reproduit bien

Une fois le service MySQL 8 actif, une commande wp-env run cli wp db query "SELECT VERSION();" confirme la version réellement utilisée par WordPress. Sur ce projet, le bug signalé s’est effectivement reproduit dès cette étape, confirmant que la cause venait bien d’une différence de comportement entre MySQL 5.7 et MySQL 8 sur la gestion d’une contrainte de clé étrangère, et non d’un problème de code indépendant de la base.

Ne jamais accepter un rapport de bug lié à une version de base de données sans avoir reproduit exactement cette version : la moitié du temps de diagnostic se joue avant d’écrire la moindre ligne de correctif.

Revenir à un environnement wp-env standard

Une fois le diagnostic terminé, un simple wp-env destroy suivi de wp-env start restaure l’environnement par défaut sans laisser de trace du service MySQL 8 personnalisé, ce qui évite de polluer les environnements de développement habituels des autres contributeurs du projet qui n’ont pas besoin de cette configuration spécifique.

En résumé

wp-env ne propose pas nativement de changer la version du service MySQL depuis .wp-env.json, mais son fonctionnement basé sur Docker Compose reste accessible et modifiable pour qui a besoin de reproduire un environnement précis. Cette manipulation reste ponctuelle et ne doit pas devenir l’environnement de développement quotidien, au risque de perdre la simplicité que wp-env apporte justement à l’ensemble des contributeurs du projet.