Ent­wick­lungs­um­ge­bung für Word­Press mit Xde­bug unter Docker

Ich ent­wick­le mit vscode unter Linux von Zeit zu Zeit The­mes oder Plug­ins für Word­Press. Für Tests und Debug­ging braucht man frü­her oder spä­ter eine spe­zi­el­le Umge­bung, in der man sein Pro­jekt in der Word­Press-Umge­bung lau­fen las­sen, tes­ten und debug­gen kann. Vscode bie­tet alle Tools, um eine sol­che Umge­bung unter Docker ein­zu­rich­ten und zu verwalten.

Eine sehr gute Anlei­tung für die Erstel­lung einer sol­che Test­um­ge­bung bie­tet Mario Yepes mit „Word­press (PHP) debug­ging in your IDE using Docker and Xde­bug”. Mit eini­gen klei­nen Ände­run­gen passt sie sehr gut in mei­ne Umge­bung. Bedeu­tends­ter Unter­schie ist, dass ich statt Win­dows mit Docker-Desk­top bei mir (Debi­an) Linux mit Docker nutze.

Vor­aus­set­zun­gen

Neben ein wenig Erfah­rung mit eine IDE wie vscode, Docker und Word­Press brauchst Du als Vor­aus­set­zung fol­gen­de Komponenten:

  • Die Ent­wick­lungs­um­ge­bung vscode
    Um Neben­wir­kun­gen mit ande­ren Ein­stel­lun­gen zu ver­mei­den, soll­te sie am bes­ten frisch instal­liert oder mit einem eige­nen Pro­fi­le indi­vi­dua­li­siert sein. Die Anlei­tung soll­te sich sinn­ge­mäß auch für ande­re IDEs anwen­den las­sen, dar­auf gehe ich im Fol­gen­den aber nicht ein.
  • Die Vir­tua­li­sie­rungs­um­ge­bung Docker inklu­si­ve docker-compose

Word­Press-Con­tai­ner erzeugen

Zunächst musst Du einen Docker-Con­tai­ner erzeu­gen, der Word­Press mit sei­ner Daten­bank und einem Web-Ser­ver aus­führt. Zur Demons­tra­ti­on des Debug­gens lege ich dar­in ein tri­via­les Plug­in an.

mkdir wp-docker
cd wp-docker
touch Dockerfile docker-compose.yaml plugin.php

Die Datei docker-compose.yaml defi­niert, wie Docker die Con­tai­ner für den Word­Press- und Daten­bank-Ser­vice anle­gen soll. Sie hat (bei mir) fol­gen­den 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 offi­zi­el­len „mariadb”-Image der Con­tai­ner „wp-xdebug-db” ange­legt. Die Envi­ron­ment-Varia­blen defi­nie­ren das root Pass­wort der DB-Engi­ne („root”), den Daten­bank-Namen, einen Nut­zer und sein Pass­wort (jeweils „wordpress”). Das das Gan­ze aus­schließ­lich in einer Ent­wick­lungs­um­ge­bung läuft, mache ich mir um Sicher­heits­be­den­ken bezüg­lich der Klar­text-Pass­wor­te kei­ne Gedan­ken. Die Daten lie­gen im Docker-Volu­me „wp-xdebug-data”.

Der zwei­te Ser­vice „wp-xde­bug-wp” ent­steht aus dem offi­zi­el­len Word­Press-Image „wordpress:6-apache" (die jeweils letz­te 6er Ver­si­on von Word­Press mit einem Apa­che-Web-Ser­ver) und nutzt mit­tels der Umge­bungs­va­ria­blen die eben ange­leg­te Daten­bank. Die inter­nen Word­Press-Daten lie­gen im Docker-Volu­me „wp-xdebug-html”. Zusätz­lich wird das aktu­el­le Ver­zeich­nis des hosts (also das oben ange­leg­te Ver­zeich­nis „wp-docker”) unter das Word­Press-Plug­ins-Ver­zeich­niss des Con­tai­ners gemoun­tet. Der inter­ne Port 80 wird auf über den Port 3000 des Hosts erreich­bar sein.

Den Con­tai­ner kannst Du jetzt schon starten:

docker-compose up -d

Der ers­te Start dau­ert recht lan­ge, weil dabei die Images her­un­ter­ge­la­den und ent­packt wer­den. Der Word­Press-Ser­ver ist dann­un­ter localhost:3000 erreich­bar. Kon­fi­gu­rie­re ihn wie üblich.

Ein Plug­in anlegen

Um spä­ter etwas debug­gen zu kön­nen, lege jetzt ein mini­ma­les Plug­in an. Es tut nichts ande­res als einen zusätz­li­chen Ein­trag im Werk­zeug-Menü der Word­Press-Admin-Ober­flä­che zu erzeu­gen, die den Sta­tus der xde­bug-Erwei­te­rung des Web-Ser­vers anzeigt. Erzeu­ge dafür im „wp-docker”-Ver­zeich­nis die Datei „plugin.php” mit fol­gen­dem Inhalt (aus dem Ori­gi­nal-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-Ober­flä­che soll­te die­ses Plug­in nach Erzeu­gen der Datei sofort unter „Plugins” ange­zeigt wer­den. Wenn Du es akti­vierst und im Werk­zeug-Menü den Ein­trag „Xdebug info” aus­wählst, zeigt das Plug­in aber nur an, dass xde­bug nicht aktiv ist.

Ein Image mit Xde­bug bauen

Um Xde­bug ver­füh­bar zu machen, musst Du statt des vor­ge­ge­be­nen offi­zi­el­len Word­Press-Image ein eige­nes Image mit instal­lier­tem Xde­bug bau­en. Das klingt kom­pli­zier­ter, als es ist.

In cocker-compese.yaml muss ledig­lich die Zeile

image: wordpress:6-apache

gegen fol­gen­de getauscht werden:

build: ./

Das weist docker-com­po­se an, kein fer­ti­ges Image zu laden, son­dern ein eige­nes zu bau­en und die build-Infor­ma­tio­nen dafür im aktu­el­len Ver­zeich­nis zu suchen. Die bie­test Du ihm in Form eines Dockerfile mit fol­gen­dem 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_INI

Oben wird als Basis wie­der das offi­zi­el­le 6er Word­Press-Image mit Apa­che ver­wen­det. Die zwei­te Anwei­sung defi­niert eine Umge­bungs­va­ria­ble für den Pfad zur Xde­bug-Kon­fi­gu­ra­ti­ons­da­tei xdebug.ini, die in den wei­te­ren Zei­len mehr­mals benutzt wird.

Die drit­te Anwei­sung instal­liert mit dem PHP-Tool pecl die Erwei­te­rung xde­bug, akti­viert sie mit dem Docker-Kom­man­do „docker-php-ext-enable” und schreibt die Kon­fi­gu­ra­ti­on in die oben defi­nier­te Datei xdebug.ini.

Ein­zi­ger Knack­punkt ist hier die Defi­ni­ti­on von xdebug.client_host. Im Ori­gi­nal-Post ver­wen­det der Autor Docker-Desk­top, das den spe­zi­el­len Host­na­men „host.docker.internal” zur Ver­fü­gung stellt. Docker unter Linux tut das nicht, so dass hier statt „192.168.2.10″ die IP-Adres­se dei­nes IDE-Hosts ein­ge­tra­gen wer­den muss.

Jetzt kannst Du das Image und den Con­tai­ner erzeu­gen lassen:

docker-compose down
docker-compose up -d

Im Ter­mi­nal siehst Du wie die Erwei­te­run­gen instal­liert wer­den. Wenn der Con­tai­ner läuft. Gehst Du jetzt wie­der in die Word­Press Admin-Ober­flä­che und klickst unter „Werk­zeu­ge” auf „Xde­bug info”, soll­test Du fol­gen­des Bild sehen:

Den Xde­bug-Trig­ger senden

Damit xde­bug nicht stän­dig mit­läuft, auch wenn gar­nichts zu debug­gen ist, wird es nur akti­viert, wenn der Brow­ser einen XDEGBUG-TRIGGER sen­det. Das kann auf zwei Wegen geschehen.

Ent­we­der Du hängst an dei­ne URL den Para­me­ter XDEBUG-TRIGGER an:

http://localhost:3000/wp-admin/tools.php?page=php-info-page&XDEBUG-TRIGGER

Oder Du setzt einen ent­spre­chen­den Coo­kie. Am ein­fachs­ten und kom­for­ta­bels­ten erle­digt das für dich eine Brow­ser-Erwei­te­rung, zum Bei­spiel „Xde­bug Star­ter”. Damit kannst Du das Debug­ging jeder­zeit über einen Knopf im Brow­ser ein- oder ausschalten.

Die vscode IDE konfigurieren

Jetzt bist Du fast fer­tig. Wenn Du das Debug­ging akti­vierst, ver­sucht Xde­bug jetzt schon, dei­ne IDE unter 192.168.2.10:9003 zu errei­chen. Aber da dort noch nichts kon­fi­gu­riert ist, siehst Du unter „Diagnostic Log” noch fol­gen­den Fehler:

Falls noch nicht gesche­hen, muss spä­tes­tens jetzt die Erwei­te­rung „PHP-Debug” in vscode instal­liert wer­den. Am bes­ten tust Du das mit der Instal­la­ti­on des Erwei­te­rungs­pa­kets „PHP” von DEVSENSE, das zusätz­lich noch ande­re nütz­li­che Erwei­te­run­gen wie Code Com­ple­ter, For­mat­ter und Lin­ter u.a. mitinstalliert.

Zum Kon­fi­gu­rie­ren von vscode wäh­le im Menü unter „Run” den Ein­trag „Add Configuration”. Ein Edi­tor mit der Datei „launch.json” öff­net sich mit eini­gen Stan­dard­ein­trä­gen. Wählst Du in der ange­zeig­ten Lis­te den Punkt „PHP: Listen for Xdebug”, wird fol­gen­der Ein­trag hinzugefügt:

    {
      "name": "Listen for Xdebug",
      "type": "php",
      "request": "launch",
      "port": [
        9003,
        9000
      ]
    },

Den Port 3000 kannst Du löschen, da er nur für Xde­bug 2 rele­vant ist, wäh­rend Du Xde­bug 3 benutzt. Zusätz­lich musst Du vscode noch bei­brin­gen, wo dei­ne Quell­da­tei­en lie­gen. Das machst Du mit mit „path­Map­pings” vom Docker-inter­nen Word­Press-Plug­in-Ver­zeich­nis auf dein Host-Ver­zeich­nis, so dass die fer­ti­ge 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}"
      }
    },

Fina­ler Test

Du bist fast am Ziel!

Um das Debug­ging zu tes­ten, set­ze einen Hal­te­punkt in der Datei „plugin.php” und star­te den Debug­ger in der IDE mit „Run” -> „Start Debug­ging”. Schal­te dann über den Xde­bug-Star­ter im Brow­ser das Debug­ging ein und rufe dei­ne Plug­in-Sei­te auf. Die IDE soll­te jetzt am Hal­te­punkt war­ten, so dass Du schritt­wei­se durch dei­ne Quel­le lau­fen kannst:

Die Datei­en Docker­file und docker-com­po­se-yaml kannst Du jetzt für belie­bi­ge Pro­jek­te ver­wen­den. Lege ein­fach ein neu­es Pro­jekt-Ver­zeich­nis an, kopie­ren die bei­den Datei­en hin­ein, ände­re ggfs. Namen und Pfa­de und star­te den Con­tai­ner mit

docker-compose up -d

Statt des Bei­spiel-Plug­ins in „plugin.php” legst Du dei­ne eige­nen Plug­in-Datei­en dann in die­sem Ver­zeich­nis an. Die Docker-Datei­en kannst Du auch nach­träg­lich in ein bestehen­des Pro­jekt-Ver­zeich­nis einbauen.

Docker-Unter­stüt­zung in vscode

Die vscode-Ent­wick­lungs­um­ge­bung bie­tet auch etwas zusätz­liche Unter­stüt­zung für das Con­tai­ner-Manage­ment an. Die Erwei­te­run­gen „Docker”, „Com­po­ser”, „Dev-Con­tai­ners” und „YAML” kannst Du instal­lie­ren, um das Con­tai­ner-Manage­ment (star­ten, stop­pen etc) aus der IDE her­aus zu erle­di­gen und die Syn­tax-Unter­stüt­zung für Datei­en im yaml-For­mat hinzuzufügen.

Grund­la­gen

Xde­bug ist eine PHP-Erwei­te­rung, die die PHP-Soft­ware­ent­wick­lung mit ver­schie­de­nen Funk­tio­nen unter­stützt. Dazu zäh­len das schritt­wei­se Abar­bei­ten von Scrip­ten zum Debug­gen, das Pro­to­kol­lie­ren von Funk­ti­ons­auf­ru­fen und Varia­blen­än­de­run­gen, Funk­tio­nen für die Leis­tungs­op­ti­mie­rung und Unter­stüt­zung von Tests.

Es wird auf dem Sys­tem, auf dem der Web­ser­ver mit PHP läuft, instal­liert und kann auf ver­schie­de­ne Arten akti­viert und genutzt wer­den. In die­sem Fall wird Xde­bug mit einem Trig­ger gestar­tet, der ent­we­der als Teil der URL oder als Coo­kie beim Auf­ruf eines PHP-Scripts mit­ge­sen­det wird.

Xde­bug mel­det sich dann beim Cli­ent-Sys­tem auf dem kon­fi­gu­rier­ten Port und war­tet auf Anweisungen.

Das Cli­ent-Sys­tem, also der PC, auf dem die PHP-Ent­wick­lungs­um­ge­bung läuft., muss den zwei­ten Teil des Debug-Sys­tems lie­fern. In die­sem Fal­le ist das vscode mit der Erwei­te­rung PHP-Debug. Die Kon­fi­gu­ra­ti­on erfolgt über die Datei launch.json, in der u.a. der Port und das Map­ping der Ver­zeich­nis­se defi­niert wird.

Docker ist eine Vir­tua­li­sie­rungs­um­ge­bung, in Soft­ware mit allen Abhän­gig­kei­ten aus vor­ge­fer­tig­ten oder selbst gebau­te Images in abge­schlos­se­nen Con­tai­nern ähn­lich einer vir­tu­el­len Maschi­ne läuft. Vie­le Soft­ware­sys­te­me wer­den von den Ent­wick­lern selbst als „offi­zi­el­le” Images auf dem Pro­jekt­ar­chiv „Docker Hub” zur Ver­fü­gung gestellt.

Wei­te­re Informationen

Schreibe einen Kommentar

Deine E-Mail-Adresse wird nicht veröffentlicht. Erforderliche Felder sind mit * markiert

fünf × drei =