Configurare un ambiente di sviluppo locale per WordPress con Docker, Xdebug e PhpStorm

Con Docker Compose, Xdebug e PhpStorm, puoi creare un ambiente di sviluppo locale riproducibile, isolato e facilmente gestibile che rispecchia un server di produzione, migliorando la qualità dei tuoi progetti WordPress.

Ciao a tutti gli sviluppatori WordPress e agli utenti avanzati! Oggi sono entusiasta di condividere un tutorial completo ma semplice su come configurare un ambiente di sviluppo locale per WordPress utilizzando Docker Compose. Essendo entrato di recente a far parte del dinamico team di OnTheGoSystems, ho deciso di portare con me la mia zona di comfort, che è l’essenza di questa configurazione.

L’obiettivo era semplice: sviluppare una configurazione in cui potessi avere un controllo granulare sui miei strumenti di sviluppo, integrando Xdebug e WP-CLI con l’immagine Docker ufficiale di WordPress. Questa configurazione non ha lo scopo di reinventare la ruota, ma di personalizzarla per allinearla alle preferenze individuali e agli stili di lavoro. Spero che questa guida ti sia utile per configurare un ambiente simile, migliorando il tuo percorso nello sviluppo di WordPress.

Prerequisiti

Per ottenere il massimo da questo tutorial, dovrai avere le seguenti dipendenze installate:

1. Docker: Useremo Docker come strumento principale per creare, distribuire ed eseguire applicazioni utilizzando i container. Ci permette di impacchettare un’applicazione con tutte le parti di cui ha bisogno in un container e di distribuirla come un unico pacchetto. Ciò che rende Docker ancora più potente è la sua promessa di controllo granulare, che ci consente di definire con precisione ogni aspetto della configurazione della nostra applicazione. Questo controllo aiuta a creare un ambiente di sviluppo che si adatta esattamente alle nostre esigenze.
2. Estensione Xdebug per Chrome: Questa estensione del browser ci aiuterà a scorrere il nostro codice, individuare i bug e migliorare la qualità generale dei nostri progetti WordPress.
3. PhpStorm: Un IDE intelligente e completo per PHP sviluppato da JetBrains. Fornisce un editor per PHP, HTML e JavaScript con analisi del codice in tempo reale e refactoring automatizzato per questi linguaggi.

Perché Docker, Xdebug e PhpStorm?

Il nostro obiettivo è stabilire un ambiente di sviluppo locale per WordPress che sia isolato, riproducibile e facilmente gestibile. Docker costituisce la spina dorsale di questa configurazione, fornendo l’infrastruttura per contenere e gestire la nostra applicazione. Xdebug e PhpStorm sono i pezzi complementari di questo puzzle, offrendo funzionalità avanzate di sviluppo e debug del codice PHP.

Il nostro viaggio inizierà con la creazione di un Dockerfile che estende l’immagine Docker ufficiale di WordPress. Miglioreremo questa immagine incorporando Xdebug e WP-CLI, strumenti fondamentali per le nostre attività di sviluppo e debug di WordPress.

Successivamente, prepareremo un file Docker Compose per orchestrare due servizi chiave: WordPress e MySQL. E, che tu ci creda o no, questo è essenzialmente tutto!

La bellezza di questa configurazione è che si traduce in un ambiente di sviluppo locale che non solo rispecchia un server di produzione, ma è anche facilmente replicabile. Ciò significa che possiamo duplicare l’esatta configurazione su più ambienti o macchine con facilità, garantendo coerenza e riducendo i problemi legati alla configurazione.

Tutorial passo dopo passo

Passo 1: il Dockerfile

Il nostro viaggio inizia con la creazione di un nuovo Dockerfile. Questo file istruisce Docker su come costruire la nostra immagine. Ecco la configurazione di base da cui parto di solito:

# 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

In questo Dockerfile, partiamo dall’immagine ufficiale di WordPress. Installiamo poi Xdebug e WP-CLI separatamente per chiarezza e manutenibilità. Il file di configurazione di Xdebug (xdebug.ini) viene copiato nella directory appropriata nel container. Questo costituisce la base della mia configurazione di riferimento per un ambiente di sviluppo locale per WordPress.

Passo 2: il file di configurazione di Xdebug (xdebug.ini)

Ora che abbiamo installato Xdebug nella nostra immagine Docker, dobbiamo configurarlo per funzionare nel nostro ambiente di sviluppo locale. Ciò comporta la creazione di un file xdebug.ini con le seguenti impostazioni:

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

Queste impostazioni abilitano l’estensione Xdebug, la impostano per avviare il debug a ogni richiesta e definiscono la porta del client a cui dovrebbe connettersi (in questo caso, 9003). Potresti aver notato che non abbiamo ancora specificato un client_host, ma non temere, entrerà in gioco molto presto nel nostro processo di configurazione.

Passo 3: il file Docker Compose

Successivamente, creeremo un file docker-compose.yml che configura i nostri servizi WordPress e 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:

In questo file, abbiamo definito due servizi: MySQL e WordPress. Entrambi questi servizi hanno nomi di container univoci, per un riferimento e una gestione più semplici.

La direttiva restart: always garantisce che il servizio si riavvii sempre se si interrompe in modo imprevisto. Se viene interrotto manualmente, viene riavviato solo quando il container viene riavviato manualmente.

Il servizio MySQL monta un volume Docker (db_data), garantendo un’archiviazione persistente anche se il container viene eliminato. Per il servizio WordPress, stiamo montando una directory locale (./wp_data) nel container. Ciò significa che qualsiasi modifica nei file di WordPress sul nostro sistema locale si rifletterà nel container.

Abbiamo aggiunto due variabili d’ambiente aggiuntive per il servizio WordPress: WORDPRESS_DEBUG per abilitare il debug di WordPress e XDEBUG_CONFIG per specificare l’host del client per Xdebug. Il client_host è impostato su host.docker.internal, che è un nome DNS speciale che indirizza all’indirizzo IP interno dell’host, consentendo a Xdebug di comunicare con il nostro IDE sull’host.

Tieni presente che l’impostazione client_host è pensata per Windows e macOS. Per Linux, un’alternativa comune è sostituire host.docker.internal con l’indirizzo IP effettivo della tua macchina, che può essere ottenuto tramite il comando da terminale ip addr show.

Passo 4: eseguire l’ambiente di sviluppo locale per WordPress

Una volta che il tuo Dockerfile, il file di configurazione di Xdebug e il file Docker Compose sono pronti, è il momento di dare vita al tuo ambiente di sviluppo locale per WordPress.

Per farlo, naviga semplicemente nella directory contenente il tuo file Docker Compose nel terminale ed esegui il seguente comando:

bash
docker-compose up -d

Questo comando istruirà Docker ad avviare i tuoi servizi in background.

Al termine dell’esecuzione, avrai un sito WordPress in esecuzione sulla tua macchina locale, accessibile tramite http://localhost:8000. Qualsiasi modifica apportata ai tuoi file PHP di WordPress si rifletterà ora su questo sito, offrendo un modo semplice ed efficace per sviluppare ed eseguire il debug della tua applicazione WordPress.

Inoltre, anche il tuo servizio MySQL sarà attivo e funzionante, accessibile sulla porta 3306. Questo fornisce un database MySQL perfettamente funzionante per la tua applicazione WordPress, replicando un ambiente realistico per le tue esigenze di sviluppo.

Passo 4.5: passo bonus – aggiungere il file phpinfo.php

Per coloro che vogliono approfondire un po’ di più la propria configurazione PHP, possiamo introdurre un file phpinfo.php nella nostra immagine Docker. Quando vi si accede, questo file presenterà una panoramica completa delle tue impostazioni PHP.
Per aggiungere il file phpinfo.php, dovrai prima crearlo nella stessa directory del tuo Dockerfile. Il file dovrebbe contenere il seguente codice PHP:

<?php phpinfo(); ?>

Successivamente, aggiungi la seguente riga al tuo Dockerfile:

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

Questo comando copierà il file phpinfo.php nella directory principale di WordPress all’interno dell’immagine Docker.

Per assicurarti che queste modifiche abbiano effetto, dovrai ricostruire la tua immagine Docker e riavviare i servizi Docker Compose. Esegui i seguenti comandi nel tuo terminale:

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

Il comando docker-compose down interrompe e rimuove i tuoi attuali container Docker. Successivamente, docker-compose up -d –build ricostruisce l’immagine Docker con il file phpinfo.php appena aggiunto e riavvia i tuoi servizi WordPress e MySQL in background.
Ora puoi accedere al file phpinfo.php navigando su http://localhost:8000/phpinfo.php nel tuo browser web. Qui vedrai una pagina dettagliata che delinea la tua configurazione PHP, che può essere una risorsa preziosa per il debug e la verifica.

Passo 5: avviare il debug

Ora che hai configurato il tuo ambiente di sviluppo locale per WordPress con Docker, Xdebug e PhpStorm, puoi iniziare a eseguire il debug del tuo sito WordPress. Ecco un rapido riepilogo di come iniziare:

1. Configurare Xdebug in PhpStorm: Apri PhpStorm e vai su File → Settings (Preferences su Mac) → Languages & Frameworks → PHP → Debug. Sotto la sezione Xdebug, assicurati che Debug port sia impostato su 9003 e che l’opzione Can accept external connections sia selezionata.
2. Aggiungere un server PhpStorm: Naviga su PHP → Servers. Aggiungi un nuovo server con il nome wordpress e l’host localhost. Imposta la porta su 8000. Assicurati che le mappature dei percorsi siano impostate correttamente: il percorso assoluto sul server per la cartella wp_data dovrebbe essere /var/www/html.
3. Installare l’estensione Xdebug helper: Installa l’estensione Xdebug helper per Google Chrome. Una volta installata, fai clic sull’icona del bug e imposta la chiave IDE su PHPSTORM.
4. Iniziare ad ascoltare le connessioni PHP Debug: In PhpStorm, fai clic sull’icona del bug nell’angolo in alto a destra per iniziare ad ascoltare le connessioni PHP Debug.
5. Avviare il debug: Una volta completati i passaggi precedenti, sei pronto per iniziare il debug della tua applicazione WordPress. Imposta semplicemente i tuoi breakpoint in PhpStorm secondo necessità, quindi ricarica il tuo sito web. Buon debug!

Conclusione

Concludendo questo tutorial, spero che diventi una risorsa preziosa per te come lo è stata per me nel mio percorso. La possibilità di personalizzare questa configurazione, come abbiamo fatto aggiungendo il file phpinfo.php, apre una miriade di possibilità, rendendo il nostro processo di sviluppo più solido ed efficiente. Tutto il codice è disponibile in questo repository GitHub. Non esitare a farne il pull, provarlo e suggerire miglioramenti!

Personalmente uso un sistema operativo Ubuntu, ma la bellezza di questa configurazione è che, grazie a Docker, non ha importanza! Grazie al fatto che Docker può essere eseguito su qualsiasi sistema operativo allo stesso modo, che tu preferisca macOS, Windows o Linux, la configurazione e l’uso sono gli stessi!

Grazie per avermi accompagnato in questa guida passo passo. Spero di avere tue notizie sulle tue esperienze o su eventuali suggerimenti che potresti avere per migliorare ulteriormente questa configurazione. Ricorda, la crescita prospera sulla conoscenza condivisa e sullo spirito di collaborazione.

Buona programmazione e continuiamo a creare fantastiche esperienze WordPress insieme!