Inhalt
Ich entwickle mit vscode unter Linux von Zeit zu Zeit Themes oder Plugins für WordPress. Für Tests und Debugging braucht man früher oder später eine spezielle Umgebung, in der man sein Projekt in der WordPress-Umgebung laufen lassen, testen und debuggen kann. Vscode bietet alle Tools, um eine solche Umgebung unter Docker einzurichten und zu verwalten.
Eine sehr gute Anleitung für die Erstellung einer solche Testumgebung bietet Mario Yepes mit „Wordpress (PHP) debugging in your IDE using Docker and Xdebug”. Mit einigen kleinen Änderungen passt sie sehr gut in meine Umgebung. Bedeutendster Unterschie ist, dass ich statt Windows mit Docker-Desktop bei mir (Debian) Linux mit Docker nutze.
Voraussetzungen
Neben ein wenig Erfahrung mit eine IDE wie vscode, Docker und WordPress brauchst Du als Voraussetzung folgende Komponenten:
- Die Entwicklungsumgebung vscode
Um Nebenwirkungen mit anderen Einstellungen zu vermeiden, sollte sie am besten frisch installiert oder mit einem eigenen Profile individualisiert sein. Die Anleitung sollte sich sinngemäß auch für andere IDEs anwenden lassen, darauf gehe ich im Folgenden aber nicht ein. - Die Virtualisierungsumgebung Docker inklusive docker-compose
WordPress-Container erzeugen
Zunächst musst Du einen Docker-Container erzeugen, der WordPress mit seiner Datenbank und einem Web-Server ausführt. Zur Demonstration des Debuggens lege ich darin ein triviales Plugin an.
mkdir wp-docker
cd wp-docker
touch Dockerfile docker-compose.yaml plugin.phpDie Datei docker-compose.yaml definiert, wie Docker die Container für den WordPress- und Datenbank-Service anlegen soll. Sie hat (bei mir) folgenden Inhalt:
version: '3'
services:
db:
image: mariadb
container_name: wp-xdebug-db
environment:
MYSQL_ROOT_PASSWORD: root
MYSQL_DATABASE: wordpress
MYSQL_USER: wordpress
MYSQL_PASSWORD: wordpress
volumes:
- wp-xdebug-data:/var/lib/mysql
wp:
image: wordpress:6-apache
container_name: wp-xdebug-wp
environment:
WORDPRESS_DB_HOST: wp-xdebug-db
WORDPRESS_DB_USER: wordpress
WORDPRESS_DB_PASSWORD: wordpress
WORDPRESS_DB_NAME: wordpress
volumes:
- wp-xdebug-html:/var/www/html
- ./:/var/www/html/wp-content/plugins/wordpress-docker-xdebug
ports:
- 3000:80
volumes:
wp-xdebug-data:
wp-xdebug-html:
networks:
default:
name: wp-xdebug-network
Oben wird aus dem offiziellen „mariadb”-Image der Container „wp-xdebug-db” angelegt. Die Environment-Variablen definieren das root Passwort der DB-Engine („root”), den Datenbank-Namen, einen Nutzer und sein Passwort (jeweils „wordpress”). Das das Ganze ausschließlich in einer Entwicklungsumgebung läuft, mache ich mir um Sicherheitsbedenken bezüglich der Klartext-Passworte keine Gedanken. Die Daten liegen im Docker-Volume „wp-xdebug-data”.
Der zweite Service „wp-xdebug-wp” entsteht aus dem offiziellen WordPress-Image „wordpress:6-apache" (die jeweils letzte 6er Version von WordPress mit einem Apache-Web-Server) und nutzt mittels der Umgebungsvariablen die eben angelegte Datenbank. Die internen WordPress-Daten liegen im Docker-Volume „wp-xdebug-html”. Zusätzlich wird das aktuelle Verzeichnis des hosts (also das oben angelegte Verzeichnis „wp-docker”) unter das WordPress-Plugins-Verzeichniss des Containers gemountet. Der interne Port 80 wird auf über den Port 3000 des Hosts erreichbar sein.
Den Container kannst Du jetzt schon starten:
docker-compose up -dDer erste Start dauert recht lange, weil dabei die Images heruntergeladen und entpackt werden. Der WordPress-Server ist dannunter localhost:3000 erreichbar. Konfiguriere ihn wie üblich.
Ein Plugin anlegen
Um später etwas debuggen zu können, lege jetzt ein minimales Plugin an. Es tut nichts anderes als einen zusätzlichen Eintrag im Werkzeug-Menü der WordPress-Admin-Oberfläche zu erzeugen, die den Status der xdebug-Erweiterung des Web-Servers anzeigt. Erzeuge dafür im „wp-docker”-Verzeichnis die Datei „plugin.php” mit folgendem Inhalt (aus dem Original-Post von Mario übernommen):
<?php
/**
* WordPress Docker Xdebug plugin
*
* @package WpDockerXdebug
* @author Mario Yepes
* @copyright 2020 Mario Yepes
* @license GPL-2.0-or-later
*
* @wordpress-plugin
* Plugin Name: WordPress Docker Xdebug plugin
* Plugin URI: https://marioyepes.com
* Description: A plugin that shows the status of Xdebug in Tools > Xdebug Info
* Version: 1.0.0
* Requires at least: 5.2
* Requires PHP: 7.2
* Author: Mario Yepes
* Author URI: https://marioyepes.com
* Text Domain: wordpress-docker-xdebug
* License: GPL v2 or later
* License URI: http://www.gnu.org/licenses/gpl-2.0.txt
* Update URI: https://marioyepes.com
*/
add_action( 'admin_menu', 'add_php_info_page' );
function add_php_info_page() {
add_submenu_page(
'tools.php', // Parent page
'Xdebug Info', // Menu title
'Xdebug Info', // Page title
'manage_options', // user "role"
'php-info-page', // page slug
'php_info_page_body'); // callback function
}
function php_info_page_body() {
$message = '<h2>No Xdebug enabled</h2>';
if ( function_exists( 'xdebug_info' ) ) {
xdebug_info();
} else {
echo $message;
}
}In der Admin-Oberfläche sollte dieses Plugin nach Erzeugen der Datei sofort unter „Plugins” angezeigt werden. Wenn Du es aktivierst und im Werkzeug-Menü den Eintrag „Xdebug info” auswählst, zeigt das Plugin aber nur an, dass xdebug nicht aktiv ist.
Ein Image mit Xdebug bauen
Um Xdebug verfühbar zu machen, musst Du statt des vorgegebenen offiziellen WordPress-Image ein eigenes Image mit installiertem Xdebug bauen. Das klingt komplizierter, als es ist.
In cocker-compese.yaml muss lediglich die Zeile
image: wordpress:6-apachegegen folgende getauscht werden:
build: ./Das weist docker-compose an, kein fertiges Image zu laden, sondern ein eigenes zu bauen und die build-Informationen dafür im aktuellen Verzeichnis zu suchen. Die bietest Du ihm in Form eines Dockerfile mit folgendem Inhalt an:
# Source image
FROM wordpress:6-apache
# We're going to use this path multile times. So save it in a variable.
ARG XDEBUG_INI="/usr/local/etc/php/conf.d/xdebug.ini"
# Install AND configure Xdebug
RUN pecl install xdebug \
&& docker-php-ext-enable xdebug \
&& echo "[xdebug]" > $XDEBUG_INI \
&& echo "xdebug.mode = debug" >> $XDEBUG_INI \
&& echo "xdebug.start_with_request = trigger" >> $XDEBUG_INI \
&& echo "xdebug.client_port = 9003" >> $XDEBUG_INI \
&& echo "xdebug.client_host = '192.168.2.10'" >> $XDEBUG_INI \
&& echo "xdebug.log = /tmp/xdebug.log" >> $XDEBUG_INI \
&& echo "xdebug.remote_enable = 1" >> $XDEBUG_INI\
&& echo "xdebug.remote_autostart = 1" >> $XDEBUG_INIOben wird als Basis wieder das offizielle 6er WordPress-Image mit Apache verwendet. Die zweite Anweisung definiert eine Umgebungsvariable für den Pfad zur Xdebug-Konfigurationsdatei xdebug.ini, die in den weiteren Zeilen mehrmals benutzt wird.
Die dritte Anweisung installiert mit dem PHP-Tool pecl die Erweiterung xdebug, aktiviert sie mit dem Docker-Kommando „docker-php-ext-enable” und schreibt die Konfiguration in die oben definierte Datei xdebug.ini.
Einziger Knackpunkt ist hier die Definition von xdebug.client_host. Im Original-Post verwendet der Autor Docker-Desktop, das den speziellen Hostnamen „host.docker.internal” zur Verfügung stellt. Docker unter Linux tut das nicht, so dass hier statt „192.168.2.10″ die IP-Adresse deines IDE-Hosts eingetragen werden muss.
Jetzt kannst Du das Image und den Container erzeugen lassen:
docker-compose down
docker-compose up -dIm Terminal siehst Du wie die Erweiterungen installiert werden. Wenn der Container läuft. Gehst Du jetzt wieder in die WordPress Admin-Oberfläche und klickst unter „Werkzeuge” auf „Xdebug info”, solltest Du folgendes Bild sehen:
Den Xdebug-Trigger senden
Damit xdebug nicht ständig mitläuft, auch wenn garnichts zu debuggen ist, wird es nur aktiviert, wenn der Browser einen XDEGBUG-TRIGGER sendet. Das kann auf zwei Wegen geschehen.
Entweder Du hängst an deine URL den Parameter XDEBUG-TRIGGER an:
http://localhost:3000/wp-admin/tools.php?page=php-info-page&XDEBUG-TRIGGEROder Du setzt einen entsprechenden Cookie. Am einfachsten und komfortabelsten erledigt das für dich eine Browser-Erweiterung, zum Beispiel „Xdebug Starter”. Damit kannst Du das Debugging jederzeit über einen Knopf im Browser ein- oder ausschalten.
Die vscode IDE konfigurieren
Jetzt bist Du fast fertig. Wenn Du das Debugging aktivierst, versucht Xdebug jetzt schon, deine IDE unter 192.168.2.10:9003 zu erreichen. Aber da dort noch nichts konfiguriert ist, siehst Du unter „Diagnostic Log” noch folgenden Fehler:
Falls noch nicht geschehen, muss spätestens jetzt die Erweiterung „PHP-Debug” in vscode installiert werden. Am besten tust Du das mit der Installation des Erweiterungspakets „PHP” von DEVSENSE, das zusätzlich noch andere nützliche Erweiterungen wie Code Completer, Formatter und Linter u.a. mitinstalliert.
Zum Konfigurieren von vscode wähle im Menü unter „Run” den Eintrag „Add Configuration”. Ein Editor mit der Datei „launch.json” öffnet sich mit einigen Standardeinträgen. Wählst Du in der angezeigten Liste den Punkt „PHP: Listen for Xdebug”, wird folgender Eintrag hinzugefügt:
{
"name": "Listen for Xdebug",
"type": "php",
"request": "launch",
"port": [
9003,
9000
]
},Den Port 9000 kannst Du löschen, da er nur für Xdebug 2 relevant ist, während Du Xdebug 3 benutzt. Zusätzlich musst Du vscode noch beibringen, wo deine Quelldateien liegen. Das machst Du mit mit „pathMappings” vom Docker-internen WordPress-Plugin-Verzeichnis auf dein Host-Verzeichnis, so dass die fertige Datei dann so aussieht:
{
"name": "Listen for Xdebug",
"type": "php",
"request": "launch",
"port": 9003,
"pathMappings": {
"/var/www/html/wp-content/plugins/wordpress-docker-xdebug": "${workspaceFolder}"
}
},Finaler Test
Du bist fast am Ziel!
Um das Debugging zu testen, setze einen Haltepunkt in der Datei „plugin.php” und starte den Debugger in der IDE mit „Run” -> „Start Debugging”. Schalte dann über den Xdebug-Starter im Browser das Debugging ein und rufe deine Plugin-Seite auf. Die IDE sollte jetzt am Haltepunkt warten, so dass Du schrittweise durch deine Quelle laufen kannst:
Die Dateien Dockerfile und docker-compose-yaml kannst Du jetzt für beliebige Projekte verwenden. Lege einfach ein neues Projekt-Verzeichnis an, kopieren die beiden Dateien hinein, ändere ggfs. Namen und Pfade und starte den Container mit
docker-compose up -dStatt des Beispiel-Plugins in „plugin.php” legst Du deine eigenen Plugin-Dateien dann in diesem Verzeichnis an. Die Docker-Dateien kannst Du auch nachträglich in ein bestehendes Projekt-Verzeichnis einbauen.
Docker-Unterstützung in vscode
Die vscode-Entwicklungsumgebung bietet auch etwas zusätzliche Unterstützung für das Container-Management an. Die Erweiterungen „Docker”, „Composer”, „Dev-Containers” und „YAML” kannst Du installieren, um das Container-Management (starten, stoppen etc) aus der IDE heraus zu erledigen und die Syntax-Unterstützung für Dateien im yaml-Format hinzuzufügen.
Grundlagen
Xdebug ist eine PHP-Erweiterung, die die PHP-Softwareentwicklung mit verschiedenen Funktionen unterstützt. Dazu zählen das schrittweise Abarbeiten von Scripten zum Debuggen, das Protokollieren von Funktionsaufrufen und Variablenänderungen, Funktionen für die Leistungsoptimierung und Unterstützung von Tests.
Es wird auf dem System, auf dem der Webserver mit PHP läuft, installiert und kann auf verschiedene Arten aktiviert und genutzt werden. In diesem Fall wird Xdebug mit einem Trigger gestartet, der entweder als Teil der URL oder als Cookie beim Aufruf eines PHP-Scripts mitgesendet wird.
Xdebug meldet sich dann beim Client-System auf dem konfigurierten Port und wartet auf Anweisungen.
Das Client-System, also der PC, auf dem die PHP-Entwicklungsumgebung läuft., muss den zweiten Teil des Debug-Systems liefern. In diesem Falle ist das vscode mit der Erweiterung PHP-Debug. Die Konfiguration erfolgt über die Datei launch.json, in der u.a. der Port und das Mapping der Verzeichnisse definiert wird.
Docker ist eine Virtualisierungsumgebung, in Software mit allen Abhängigkeiten aus vorgefertigten oder selbst gebaute Images in abgeschlossenen Containern ähnlich einer virtuellen Maschine läuft. Viele Softwaresysteme werden von den Entwicklern selbst als „offizielle” Images auf dem Projektarchiv „Docker Hub” zur Verfügung gestellt.
Weitere Informationen
- XDebug: https://xdebug.org/
- vscode: https://code.visualstudio.com/
- Docker: https://www.docker.com/
- Docker Hub: https://hub.docker.com/