Lokale Entwicklungsumgebung für WordPress-Plugins mit wp-env einrichten

Entwickeln Sie ein Plugin nie direkt auf einer Live-Website. Eine lokale Umgebung trennt Ihre Arbeit sauber vom Produktivsystem: Sie können ausprobieren, Fehler provozieren und alles wieder zurücksetzen, ohne dass Besucher etwas davon merken. Das offizielle Werkzeug dafür heißt wp-env (Paket @wordpress/env). Es startet WordPress in einer isolierten Installation auf Ihrem Rechner und bindet Ihr Plugin direkt aus dem Projektordner ein. Sie bearbeiten die Dateien also dort, wo sie ohnehin liegen, und sehen das Ergebnis sofort in der lokalen Installation.

wp-env wird über die Kommandozeile bedient und nutzt in der Grundeinstellung Docker, um WordPress, Datenbank und Hilfsdienste bereitzustellen. Weil die Konfiguration als Datei im Projekt liegt, erhält jede Person im Team dieselbe Umgebung. Ein Ersatz für einen Server ist das nicht: Was Sie lokal ändern, wirkt sich nicht auf ein Live-System aus.

Wie ein Plugin grundsätzlich aufgebaut ist, zeigt der Artikel WordPress-Plugin erstellen.

Voraussetzungen

Ihr Projektordner sollte die Dateien des Plugins enthalten, also mindestens die Hauptdatei mit dem Plugin-Header. Für wp-env brauchen Sie außerdem eine package.json. Fehlt sie noch, legen Sie sie mit npm init an.

Folgende Werkzeuge müssen installiert sein:

• Node.js und npm, um wp-env zu installieren und aufzurufen.
• Docker, das die Container für WordPress und die Datenbank bereitstellt.
• Ein Terminal, in dem Sie die Befehle im Projektverzeichnis ausführen.

Starten Sie Docker, bevor Sie die Umgebung hochfahren. Läuft Docker nicht oder ist es nicht erreichbar, kann wp-env keine Container starten. Rechnen Sie außerdem damit, dass die Umgebung Speicherplatz belegt und im Hintergrund Dienste ausführt, solange sie läuft.

wp-env im Plugin-Projekt installieren

Öffnen Sie das Terminal im Stammverzeichnis Ihres Plugins und installieren Sie wp-env als Entwicklungsabhängigkeit:

npm install --save-dev @wordpress/env

Das Paket landet in den devDependencies der package.json, die Lockdatei hält die genauen Versionen fest. Nehmen Sie beide Dateien in die Versionsverwaltung auf, damit alle im Team dieselbe Grundlage installieren.

Für kürzere Befehle können Sie ein Skript ergänzen:

{
  "scripts": {
    "env": "wp-env"
  }
}

Tragen Sie den Eintrag in den vorhandenen scripts-Abschnitt ein, statt bestehende Skripte zu überschreiben. Danach starten Sie die Umgebung mit npm run env start. Alternativ rufen Sie wp-env direkt mit npx wp-env auf.

Konfiguration mit .wp-env.json

Legen Sie im Stammverzeichnis eine Datei .wp-env.json an. Für den Anfang genügt wenig:

{
  "core": null,
  "plugins": ["."],
  "themes": []
}

Der Eintrag plugins bindet das Plugin aus dem aktuellen Verzeichnis ein, der Punkt steht für den Projektordner. themes bleibt hier leer, weil kein zusätzliches Theme gebraucht wird. Mit "core": null verwendet wp-env die neueste veröffentlichte WordPress-Version.

Die Datei gehört in die Versionsverwaltung. So arbeiten alle mit denselben Einstellungen, statt sie auf jedem Rechner neu zusammenzusuchen. Achten Sie darauf, dass sie keine Zugangsdaten und keine Pfade enthält, die nur auf Ihrem Rechner gelten.

Halten Sie die Konfiguration anfangs klein und ergänzen Sie Optionen erst, wenn Sie sie wirklich brauchen. Dann bleibt nachvollziehbar, was die Umgebung beeinflusst.

Debug-Einstellungen

Über den Schlüssel config legen Sie Konstanten fest, die wp-env in die wp-config.php der lokalen Installation schreibt. Laut Dokumentation sind in der Entwicklungsumgebung WP_DEBUG und SCRIPT_DEBUG bereits eingeschaltet. Warnungen, Hinweise auf veraltete Funktionen und unminifizierte Skripte des Kerns sehen Sie damit von Anfang an. Möchten Sie Meldungen zusätzlich in eine Protokolldatei schreiben lassen, ergänzen Sie zum Beispiel:

{
  "plugins": ["."],
  "config": {
    "WP_DEBUG_LOG": true
  }
}

Nach einer Änderung an der Konfiguration starten Sie die Umgebung neu, damit die Werte übernommen werden.

Die Umgebung starten und öffnen

Starten Sie Docker und führen Sie im Projektverzeichnis aus:

npx wp-env start

Beim ersten Aufruf lädt wp-env die benötigten Komponenten herunter und richtet WordPress ein. Das dauert spürbar länger als spätere Starts. Warten Sie, bis der Befehl den erfolgreichen Start meldet.

Die lokale Adresse gibt wp-env beim Start aus. Rufen Sie sie im Browser auf und melden Sie sich in der Verwaltung an. Taucht Ihr Plugin in der Plugin-Liste auf, hat wp-env es erkannt. Weiterentwickelt wird wie gehabt in den Dateien Ihres Projektordners.

Änderungen an PHP-Dateien sehen Sie nach dem Neuladen der Seite. Erscheint eine Änderung nicht, prüfen Sie zuerst, ob Sie wirklich die Datei im eingebundenen Plugin-Ordner bearbeitet haben und nicht eine Kopie an anderer Stelle.

Befehle für den Alltag

stop und destroy sind zwei sehr verschiedene Dinge. stop beendet nur die laufenden Dienste, beim nächsten Start ist alles wieder da. destroy löscht die Umgebung samt Datenbank, wp-env fragt deshalb vorher nach. Verwenden Sie den Befehl nur, wenn die lokale Installation wirklich weg soll.

WP-CLI im Container

Mit run cli führen Sie beliebige WP-CLI-Befehle in der Umgebung aus, ohne WP-CLI selbst zu installieren. Das ist praktisch, um Plugins zu aktivieren, Benutzer anzulegen oder Optionen zu prüfen. Mit der Option --env-cwd wechseln Sie vorher in ein Verzeichnis, Pfade ohne führenden Schrägstrich gelten relativ zum WordPress-Stammordner:

npx wp-env run cli --env-cwd=wp-content/plugins/mein-plugin composer install

Starten Sie solche Befehle immer im richtigen Projektordner, vor allem wenn Sie mehrere lokale Projekte parallel pflegen.

Alternativen zu wp-env

wp-env ist nicht der einzige Weg. Es gibt Desktop-Anwendungen, die lokale WordPress-Installationen per Mausklick anlegen, und Sie können auch einen lokalen Webserver mit PHP und Datenbank selbst einrichten. Welcher Weg passt, hängt von Ihrem Arbeitsstil ab. Der Vorteil von wp-env liegt darin, dass die Umgebung als Datei im Projekt beschrieben ist und sich auf jedem Rechner gleich aufbauen lässt.

Häufige Probleme eingrenzen

• Docker ist nicht erreichbar: Prüfen Sie, ob Docker läuft und Ihr Benutzer darauf zugreifen darf. Ein erneuter Start von wp-env hilft erst, wenn Docker selbst funktioniert.
• Der Start bricht ab oder hängt: Lesen Sie die vollständige Fehlermeldung im Terminal. Prüfen Sie danach, ob eine Internetverbindung für die nötigen Downloads besteht und genug Speicher frei ist.
• Das Plugin erscheint nicht: Liegt die .wp-env.json im Projektstamm, und stimmt der Pfad unter plugins? Für ein Plugin im aktuellen Ordner lautet der Eintrag ".". Prüfen Sie außerdem, ob die Hauptdatei des Plugins an der erwarteten Stelle liegt.
• Im Browser erscheint eine andere Installation: Verwenden Sie die Adresse, die wp-env beim Start ausgibt. Eine bereits vorhandene lokale WordPress-Installation läuft womöglich unter einer anderen Adresse und gehört nicht zur wp-env-Umgebung.
• Konfigurationsänderungen greifen nicht: Prüfen Sie die JSON-Syntax, vor allem Kommas und Anführungszeichen, und starten Sie die Umgebung neu. Entfernen Sie sie nicht vorschnell, wenn lokale Inhalte erhalten bleiben sollen.

Fazit

Mit wp-env steht eine lokale WordPress-Installation direkt im Plugin-Projekt bereit. Für den Einstieg genügen Docker, Node.js, eine schlanke .wp-env.json und die Befehle zum Starten und Anhalten. Halten Sie die Konfiguration in der Versionsverwaltung, und entfernen Sie die Umgebung nur, wenn Sie die lokalen Inhalte nicht mehr brauchen. Auf dieser Grundlage lassen sich auch automatische Tests einrichten, wie sie der Artikel PHPUnit für WordPress-Plugins beschreibt, und zeitgesteuerte Abläufe ausprobieren, um die es im Artikel WP-Cron richtig einsetzen geht. Weitere Themen rund um die Plugin-Entwicklung finden Sie in der Übersicht WordPress-Plugins entwickeln.