Configurer un environnement de développement WordPress local avec Docker, Xdebug et PhpStorm

Avec Docker Compose, Xdebug et PhpStorm, vous pouvez créer un environnement de développement local reproductible, isolé et facile à gérer qui reproduit un serveur de production, améliorant ainsi la qualité de vos projets WordPress.

Bonjour chers développeurs et utilisateurs avancés de WordPress ! Aujourd’hui, je suis ravi de partager un tutoriel complet mais simple sur la configuration d’un environnement de développement WordPress local à l’aide de Docker Compose. Ayant récemment rejoint l’équipe dynamique d’OnTheGoSystems, j’ai décidé d’apporter ma zone de confort avec moi, ce qui est le but de cette configuration.

L’objectif était simple : développer une configuration où je pourrais avoir un contrôle granulaire sur mes outils de développement, en intégrant Xdebug et WP-CLI à l’image Docker officielle de WordPress. Cette configuration ne vise pas à réinventer la roue, mais à la personnaliser pour l’adapter aux préférences et aux styles de travail de chacun. J’espère que ce guide vous sera utile pour configurer un environnement similaire, et qu’il facilitera votre parcours dans le développement WordPress.

Prérequis

Pour tirer le meilleur parti de ce tutoriel, vous devez avoir installé les dépendances suivantes :

Docker : nous utiliserons Docker comme outil principal pour créer, déployer et exécuter des applications à l’aide de conteneurs. Il nous permet d’empaqueter une application avec tous les éléments dont elle a besoin dans un conteneur, et de la livrer sous la forme d’un seul paquet. Ce qui rend Docker encore plus puissant, c’est sa promesse de contrôle granulaire, nous permettant de définir précisément chaque aspect de la configuration de notre application. Ce contrôle aide à concevoir un environnement de développement qui répond exactement à nos besoins.
Extension Chrome Xdebug : cette extension de navigateur nous aidera à parcourir notre code, à repérer les bogues et à améliorer la qualité globale de nos projets WordPress.
PhpStorm : un IDE intelligent et complet pour PHP développé par JetBrains. Il fournit un éditeur pour PHP, HTML et JavaScript avec une analyse de code à la volée et une refactorisation automatisée pour ces langages.

Pourquoi Docker, Xdebug et PhpStorm ?

Notre objectif est d’établir un environnement de développement WordPress local qui soit isolé, reproductible et facile à gérer. Docker constitue l’épine dorsale de cette configuration, fournissant l’infrastructure pour contenir et gérer notre application. Xdebug et PhpStorm sont les pièces complémentaires de ce puzzle, offrant des capacités améliorées de développement et de débogage de code PHP.

Notre parcours commencera par la création d’un Dockerfile qui étend l’image Docker officielle de WordPress. Nous améliorerons cette image en y incorporant Xdebug et WP-CLI, des outils essentiels dans nos tâches de développement et de débogage WordPress.

Ensuite, nous rédigerons un fichier Docker Compose pour orchestrer deux services clés : WordPress et MySQL. Et croyez-le ou non, c’est pour ainsi dire tout !

La beauté de cette configuration est qu’elle aboutit à un environnement de développement local qui non seulement reproduit un serveur de production, mais est également facilement reproductible. Cela signifie que nous pouvons dupliquer facilement la configuration exacte sur plusieurs environnements ou machines, garantissant ainsi la cohérence et réduisant les problèmes liés à la configuration.

Tutoriel étape par étape

Étape 1 : le Dockerfile

Notre parcours commence par la création d’un nouveau Dockerfile. Ce fichier indique à Docker comment construire notre image. Voici la configuration de base avec laquelle je commence généralement :

# Use the official WordPress image as a parent image
FROM wordpress:latest

# Install Xdebug
RUN pecl install xdebug 

# Install WP-CLI
RUN curl -O https://raw.githubusercontent.com/wp-cli/builds/gh-pages/phar/wp-cli.phar && \
    chmod +x wp-cli.phar && \
    mv wp-cli.phar /usr/local/bin/wp

# Copy xdebug.ini into the container
COPY xdebug.ini /usr/local/etc/php/conf.d/xdebug.ini

Dans ce Dockerfile, nous partons de l’image WordPress officielle. Nous installons ensuite Xdebug et WP-CLI séparément pour des raisons de clarté et de maintenabilité. Le fichier de configuration de Xdebug (xdebug.ini) est copié dans le répertoire approprié du conteneur. Cela constitue la base de ma configuration de prédilection pour un environnement de développement WordPress local.

Étape 2 : le fichier de configuration de Xdebug (xdebug.ini)

Maintenant que Xdebug est installé dans notre image Docker, nous devons le configurer pour qu’il fonctionne dans notre environnement de développement local. Cela implique la création d’un fichier xdebug.ini avec les paramètres suivants :

ini
zend_extension=xdebug
xdebug.mode=debug
xdebug.client_port=9003
xdebug.start_with_request=yes

Ces paramètres activent l’extension Xdebug, la configurent pour démarrer le débogage à chaque requête et définissent le port client auquel elle doit se connecter (dans ce cas, 9003). Vous avez peut-être remarqué que nous n’avons pas encore spécifié de client_host, mais ne vous inquiétez pas, il entrera en jeu très bientôt dans notre processus de configuration.

Étape 3 : le fichier Docker Compose

Ensuite, nous allons créer un fichier docker-compose.yml qui configure nos services WordPress et MySQL :

yaml
version: '3'
services:
  # MySQL Service
  mysql:
    image: mysql:latest
    container_name: mysql_container
    restart: always
    volumes:
      - db_data:/var/lib/mysql
    environment:
      MYSQL_ROOT_PASSWORD: root
      MYSQL_USER: wordpress
      MYSQL_PASSWORD: wordpress
      MYSQL_DATABASE: wordpress
  
  # WordPress Service
  wordpress:
    depends_on: 
      - mysql
    image: wordpress:latest
    container_name: wp_container
    volumes:
      - ./wp_data:/var/www/html
    environment:
      WORDPRESS_DB_HOST: mysql
      WORDPRESS_DB_USER: wordpress
      WORDPRESS_DB_PASSWORD: wordpress
      WORDPRESS_DB_NAME: wordpress
      WORDPRESS_DEBUG: 1
      XDEBUG_CONFIG: client_host=host.docker.internal
    ports:
      - "8000:8000"

volumes:
  db_data:

Dans ce fichier, nous avons défini deux services – MySQL et WordPress. Chacun de ces services possède un nom de conteneur unique, pour faciliter la référence et la gestion.

La directive restart: always garantit que le service redémarrera toujours s’il s’arrête de manière inattendue. S’il est arrêté manuellement, il n’est redémarré que lorsque le conteneur est redémarré manuellement.

Le service MySQL monte un volume Docker (db_data), garantissant un stockage persistant même si le conteneur est supprimé. Pour le service WordPress, nous montons un répertoire local (./wp_data) sur le conteneur. Cela signifie que toute modification des fichiers WordPress sur notre système local sera répercutée dans le conteneur.

Nous avons ajouté deux variables d’environnement supplémentaires pour le service WordPress – WORDPRESS_DEBUG pour activer le débogage WordPress et XDEBUG_CONFIG pour spécifier l’hôte client pour Xdebug. Le client_host est défini sur host.docker.internal, qui est un nom DNS spécial qui achemine vers l’adresse IP interne de l’hôte, permettant à Xdebug de communiquer avec notre IDE sur l’hôte.

Veuillez noter que le paramètre client_host est adapté à Windows et macOS. Pour Linux, une alternative courante consiste à remplacer host.docker.internal par l’adresse IP réelle de votre machine, qui peut être obtenue via la commande de terminal ip addr show.

Étape 4 : exécuter votre environnement de développement WordPress local

Une fois que votre Dockerfile, votre fichier de configuration Xdebug et votre fichier Docker Compose sont prêts, il est temps de donner vie à votre environnement de développement WordPress local.

Pour ce faire, naviguez simplement vers le répertoire contenant votre fichier Docker Compose dans le terminal, et exécutez la commande suivante :

bash
docker-compose up -d

Cette commande demandera à Docker de démarrer vos services en arrière-plan.

En cas d’exécution réussie, vous aurez un site WordPress fonctionnant sur votre machine locale, accessible via http://localhost:8000. Toute modification que vous apporterez à vos fichiers PHP WordPress sera désormais répercutée sur ce site, offrant un moyen simple et efficace de développer et de déboguer votre application WordPress.

De plus, votre service MySQL sera également opérationnel, accessible sur le port 3306. Cela fournit une base de données MySQL entièrement fonctionnelle pour votre application WordPress, reproduisant un environnement réaliste pour vos besoins de développement.

Étape 4.5 : étape bonus – Ajouter le fichier phpinfo.php

Pour ceux qui souhaitent approfondir un peu leur configuration PHP, nous pouvons introduire un fichier phpinfo.php dans notre image Docker. Lors de son accès, ce fichier présentera un aperçu complet de vos paramètres PHP.
Pour ajouter le fichier phpinfo.php, vous devrez d’abord le créer dans le même répertoire que votre Dockerfile. Le fichier doit contenir le code PHP suivant :

<?php phpinfo(); ?>

Ensuite, ajoutez la ligne suivante à votre Dockerfile :

# Bonus: Copy phpinfo.php into the container
COPY phpinfo.php /var/www/html/phpinfo.php

Cette commande copiera le fichier phpinfo.php dans le répertoire racine de WordPress au sein de l’image Docker.

Pour vous assurer que ces modifications prennent effet, vous devrez reconstruire votre image Docker et redémarrer les services Docker Compose. Exécutez les commandes suivantes dans votre terminal :

bash
docker-compose down
docker-compose up -d --build

La commande docker-compose down arrête et supprime vos conteneurs Docker actuels. Ensuite, docker-compose up -d –build reconstruit l’image Docker avec le fichier phpinfo.php nouvellement ajouté, et redémarre vos services WordPress et MySQL en arrière-plan.
Vous pouvez maintenant accéder au fichier phpinfo.php en naviguant vers http://localhost:8000/phpinfo.php dans votre navigateur web. Vous y verrez une page détaillée décrivant votre configuration PHP, ce qui peut être une ressource précieuse pour le débogage et la vérification.

Étape 5 : démarrer le débogage

Maintenant que vous avez configuré votre environnement de développement WordPress local avec Docker, Xdebug et PhpStorm, vous pouvez commencer à déboguer votre site WordPress. Voici un bref aperçu de la façon de démarrer :

Configurer Xdebug dans PhpStorm : ouvrez PhpStorm et allez dans Fichier → Paramètres (Préférences sur Mac) → Langages & Frameworks → PHP → Débogage. Dans la section Xdebug, assurez-vous que le Port de débogage est défini sur 9003 et que l’option Peut accepter des connexions externes est cochée.
Ajouter un serveur PhpStorm : accédez à PHP → Serveurs. Ajoutez un nouveau serveur avec le nom wordpress et l’hôte localhost. Définissez le port sur 8000. Assurez-vous que les mappages de chemins sont correctement définis – le chemin absolu sur le serveur pour le dossier wp_data doit être /var/www/html.
Installer l’extension Xdebug helper : installez l’extension Xdebug helper pour Google Chrome. Une fois installée, cliquez sur l’icône en forme d’insecte et définissez la clé IDE sur PHPSTORM.
Commencer à écouter les connexions de débogage PHP : dans PhpStorm, cliquez sur l’icône en forme d’insecte dans le coin supérieur droit pour commencer à écouter les connexions de débogage PHP.
Démarrer le débogage : une fois les étapes précédentes terminées, vous êtes prêt à commencer à déboguer votre application WordPress. Définissez simplement vos points d’arrêt dans PhpStorm selon vos besoins, puis rechargez simplement votre site web. Bon débogage !

Conclusion

Alors que nous concluons ce tutoriel, j’espère qu’il deviendra une ressource précieuse pour vous comme il l’a été pour moi dans mon parcours. La possibilité de personnaliser cette configuration – comme nous l’avons fait en ajoutant le fichier phpinfo.php – ouvre une myriade de possibilités, rendant notre processus de développement plus robuste et plus efficace. Tout le code est disponible dans ce dépôt GitHub. N’hésitez pas à le récupérer, à l’essayer et à suggérer des améliorations !

J’utilise personnellement un système d’exploitation Ubuntu, mais la beauté de cette configuration est que grâce à Docker, cela n’a pas d’importance ! Grâce au fait que Docker peut fonctionner sur n’importe quel système d’exploitation de manière égale, que vous préfériez macOS, Windows ou Linux, la configuration et l’utilisation sont les mêmes !

Merci de m’avoir accompagné dans cette présentation. J’espère que vous me ferez part de vos expériences ou de toutes suggestions que vous pourriez avoir pour améliorer encore cette configuration. N’oubliez pas que la croissance se nourrit du partage des connaissances et de l’esprit de collaboration.

Bon codage, et continuons à créer des expériences WordPress incroyables ensemble !