@wordpress/env (wp-env)

Environnement de développement WordPress local sans configuration, basé sur Docker, pour les plugins, thèmes et le core.

Quand l'utiliser

• L'utilisateur demande de configurer un environnement de développement WordPress local
• Le projet contient un fichier .wp-env.json
• L'utilisateur mentionne wp-env, @wordpress/env, ou un développement WordPress basé sur Docker
• L'utilisateur veut exécuter des commandes WP-CLI, des tests PHPUnit, ou déboguer avec Xdebug localement
• Le tri détecte un projet de plugin ou thème qui a besoin d'une instance WordPress locale

wp-env ou wp-playground ? Pour un WordPress local rapide, préférez la compétence wp-playground par défaut — c'est plus rapide, jetable, et ne nécessite pas Docker. Utilisez wp-env quand la tâche l'exige réellement :

• le dépôt contient déjà un .wp-env.json
• une vrai base de données MySQL est nécessaire (PHPUnit contre la DB, commandes wp db, données qui survivent aux redémarrages)
• des commandes arbitraires doivent s'exécuter dans l'environnement (accès shell, Composer, WP-CLI complet via wp-env run)
• c'est un checkout WordPress core ou Gutenberg
• l'utilisateur demande explicitement wp-env ou Docker

wp-env peut aussi fonctionner sans Docker en utilisant Playground comme runtime (npx @wordpress/env start --runtime=playground, expérimental). C'est toujours wp-env, piloté par le même .wp-env.json, donc traitez-le comme un fallback sans Docker pour un projet ayant déjà la configuration wp-env, pas comme une troisième option. Il remplace MySQL par SQLite et supprime wp-env run et l'environnement de tests séparé, qui sont la plupart des raisons de choisir wp-env. Pour un WordPress rapide sans Docker et sans configuration wp-env, utilisez directement la compétence wp-playground.

Entrées requises

1. Statut Docker -- vérifiez que Docker est installé et exécuté : docker info
2. Version Node.js -- doit être >= 18.12.0 : node -v
3. Type de projet -- plugin, thème, ou site complet (cherchez .wp-env.json, en-têtes de plugin, ou en-têtes de thème style.css)
4. Configuration existante -- lisez .wp-env.json et .wp-env.override.json s'ils existent

Procédure

1. Installer wp-env

# Global (recommandé)
npm -g install @wordpress/env

# Ou au niveau du projet
npm i @wordpress/env --save-dev
# Puis utilisez : npx wp-env start

2. Démarrer l'environnement

wp-env start

Identifiants par défaut :

• URL : http://localhost:8888/wp-admin/
• Nom d'utilisateur : admin
• Mot de passe : password

Options de démarrage courantes :

• wp-env start --update -- récupérer les dernières sources et reconfigurer
• wp-env start --xdebug -- activer Xdebug (mode débogage)
• wp-env start --xdebug=profile,trace -- plusieurs modes Xdebug
• wp-env start --auto-port -- trouver les ports disponibles quand les ports par défaut sont occupés

3. Auto-détection (pas de fichier de configuration)

Quand aucun .wp-env.json n'existe, wp-env analyse le répertoire courant :

4. Configurer avec .wp-env.json

Placez-le à la racine du projet. Tous les champs sont optionnels.

{
  "core": null,
  "phpVersion": "8.1",
  "plugins": [
    ".",
    "https://downloads.wordpress.org/plugin/akismet.zip",
    "WordPress/classic-editor"
  ],
  "themes": [],
  "port": 8888,
  "multisite": false,
  "phpmyadmin": false,
  "config": {
    "WP_DEBUG": true,
    "SCRIPT_DEBUG": true
  },
  "mappings": {
    "wp-content/mu-plugins": "./mu-plugins"
  },
  "lifecycleScripts": {
    "afterStart": "wp-env run cli wp rewrite structure /%postname%/"
  }
}

Formats de chaîne source (pour core, plugins, themes, mappings)

PIÈGE : Les slugs de plugin/thème WordPress.org (noms simples comme "akismet") ne fonctionnent PAS. Utilisez l'URL ZIP complète.

Remplacements locaux avec .wp-env.override.json

Créez .wp-env.override.json à côté de .wp-env.json pour les paramètres personnels (gitignorés). Seuls config et mappings sont fusionnés -- tous les autres champs (y compris les tableaux plugins et themes) remplacent entièrement la base.

5. Exécuter des commandes dans les conteneurs

# Commandes WP-CLI
wp-env run cli wp user list
wp-env run cli wp plugin list
wp-env run cli wp option update blogname "My Site"
wp-env run cli "wp rewrite structure /%postname%/"

# Exécuter les commandes dans un répertoire spécifique
wp-env run cli --env-cwd=wp-content/plugins/my-plugin composer install

# Tests PHPUnit
wp-env run cli --env-cwd=wp-content/plugins/my-plugin vendor/bin/phpunit

# Passer les flags avec le séparateur --
wp-env run cli php -- --version

# Accès MySQL
wp-env run mysql mysql -- --user=root --password=password wordpress

Conteneurs disponibles : mysql, wordpress, cli, composer, phpmyadmin.

6. Gérer l'environnement

wp-env stop                    # Arrêter et libérer les ports
wp-env reset development       # Réinitialiser la base de données dev (garde la base de test)
wp-env reset all               # Réinitialiser toutes les bases de données
wp-env logs                    # Afficher les logs PHP/Docker en continu
wp-env logs --no-watch         # Afficher les logs et quitter
wp-env status                  # Afficher les URLs, ports, configuration
wp-env status --json           # Statut lisible par machine
wp-env cleanup                 # Supprimer les conteneurs/volumes (garder les images)
wp-env destroy                 # Supprimer tout y compris les images

7. Configuration Xdebug

wp-env start --xdebug          # Activer le mode débogage
wp-env start --xdebug=coverage # Pour la couverture de code
wp-env start                   # Désactiver Xdebug (redémarrer sans le flag)

Modes : debug, profile, trace, develop, coverage.

L'IDE écoute sur le port 9003. Le launch.json de VS Code doit contenir :

{
  "type": "php",
  "request": "launch",
  "name": "Listen for Xdebug",
  "port": 9003,
  "pathMappings": {
    "/var/www/html/wp-content/plugins/your-plugin": "${workspaceFolder}"
  }
}

8. Multisite

{ "multisite": true, "plugins": ["."] }

Vérification

• [ ] wp-env status affiche les conteneurs en cours d'exécution avec les ports corrects
• [ ] http://localhost:8888/wp-admin/ charge l'admin WordPress
• [ ] wp-env run cli wp plugin list affiche les plugins attendus
• [ ] Le plugin/thème en développement apparaît dans l'admin WordPress
• [ ] Les réinitialisations de base de données fonctionnent : wp-env reset development

Modes d'échec / débogage

Escalade

• Problèmes Docker au-delà du scope de wp-env (réseau, espace disque, backend WSL2)
• Configurations Docker Compose personnalisées en conflit avec wp-env
• Intégration CI/CD nécessitant des configurations Docker non standard
• Le runtime WordPress Playground (--runtime=playground) est expérimental et a une parité de fonctionnalités limitée

Références

• Documentation officielle
• Guide de démarrage
• Code source