wp-env – Ambiente di sviluppo locale per plugin WordPress

Quarto articolo della serie sui fondamenti dello sviluppo di plugin WordPress. Negli articoli precedenti abbiamo configurato un repository Git e Composer con autoloading PSR-4. Ora ci serve un’installazione WordPress per testare il plugin.

Per sviluppare un plugin hai bisogno di un WordPress funzionante. Tradizionalmente questo significava installare MAMP, XAMPP o configurare Docker manualmente — approcci che funzionano, ma portano con sé configurazioni macchinose e ambienti difficili da replicare.

wp-env è la soluzione ufficiale del team WordPress: un comando, un ambiente di sviluppo locale completo, il tuo plugin già attivo e pronto per essere testato.

Prerequisiti: Per usare wp-env servono Docker Desktop (installato e in esecuzione) e Node.js con npm. Non serve scaricare WordPress — ci pensa wp-env.

Cos’è wp-env

wp-env è uno strumento ufficiale mantenuto dal team di WordPress core, nato nell’ambito del progetto Gutenberg. Dietro le quinte usa Docker, ma non devi configurare container o scrivere file docker-compose.yml.

Quando lo avvii, crea due istanze WordPress: una di sviluppo (porta 8888) e una di test (porta 8889). L’istanza di test diventerà utile più avanti quando parleremo di test automatizzati con PHPUnit.

Installazione e primo avvio

Installa wp-env globalmente tramite npm:

npm install -g @wordpress/env

Ora entra nella directory del plugin che abbiamo creato nei primi due articoli ed avvia l’ambiente:

cd my-awesome-plugin
wp-env start

La prima volta ci vorrà qualche minuto: wp-env scarica le immagini Docker, installa WordPress e monta la directory del tuo plugin. Alle esecuzioni successive sarà quasi istantaneo.

Una volta avviato, apri il browser:

• Frontend: http://localhost:8888
• Admin: http://localhost:8888/wp-admin
• Credenziali: admin / password

Il tuo plugin è già attivo. Ogni modifica ai file nella directory del plugin si riflette immediatamente — wp-env monta la cartella come volume Docker, quindi non serve riavviare nulla.

Per fermare l’ambiente:

wp-env stop

Il file .wp-env.json

Di default wp-env usa l’ultima versione di WordPress e PHP. Se vuoi un controllo più preciso, crea un file .wp-env.json nella root del plugin:

{
    "core": "WordPress/WordPress#6.7",
    "phpVersion": "8.2",
    "plugins": [
        "."
    ]
}

Questo file ti permette di fissare la versione di WordPress e PHP, montare plugin o temi aggiuntivi e definire mappature personalizzate per file e directory. Il vantaggio concreto: committando .wp-env.json nel repository, chiunque cloni il progetto avrà lo stesso identico ambiente con un semplice wp-env start. Più avanti nella serie vedremo come usare la stessa configurazione anche nelle GitHub Actions per i test automatizzati in CI.

Comandi utili per lo sviluppo quotidiano

Oltre a start e stop, wp-env offre alcuni comandi che userai spesso.

Per eseguire comandi WP-CLI all’interno del container:

# Lista dei plugin installati
wp-env run cli wp plugin list

# Lista degli utenti
wp-env run cli wp user list

# Attivare un plugin aggiuntivo
wp-env run cli wp plugin activate another-plugin

Per eseguire comandi sull’istanza di test:

wp-env run tests-cli wp plugin list

Per controllare i log in caso di errori:

wp-env logs

E se qualcosa va storto e vuoi ricominciare da zero:

wp-env destroy

Non serve mai entrare manualmente nei container Docker. wp-env gestisce tutto dall’esterno.

Integrazione con Composer

Un punto importante: Composer gira sulla tua macchina host, non dentro il container Docker. Quando esegui composer install o composer dump-autoload, la directory vendor/ viene creata nella cartella del plugin — che è montata dentro il container.

Il workflow quotidiano è quindi semplice: modifica il codice e gestisci Composer sulla tua macchina, wp-env riflette tutto automaticamente nell’ambiente WordPress. I due strumenti lavorano insieme senza interferire.

Con composer.json, composer.lock e .wp-env.json committati nel repository Git, il tuo setup è completamente riproducibile.

Prossimi passi

Ora hai un ambiente di sviluppo locale completo: un repository Git, Composer per autoloading e dipendenze, e wp-env per un WordPress funzionante. Questa è una base professionale su cui costruire qualsiasi plugin.

Nel prossimo articolo configureremo GitHub Actions per eseguire controlli automatici a ogni push e Pull Request. È un dettaglio interessante: wp-env funziona anche in CI, quindi potremo riutilizzare lo stesso ambiente sia in locale che nei workflow automatizzati.

Prossimo articolo: GitHub Actions per lo sviluppo di plugin WordPress →