Docker WordPress Dev Environment - Page 2

Remote Debugging with Xdebug and VS Code

In order to set breakpoints and step through the PHP code used in WordPress core, themes and plugins, The Xdebug PHP extension needs to be installed, configured and built into an image.

IP address for the xdebug.remote_host setting is needed to configure the extension.

Windows 10 Professional running Docker Version 17.03.0-ce-win1, open a command prompt and enter ipconfig. The address is listed under DockerNAT. For example:

ipconfig

Ethernet adapter vEthernet (DockerNAT):

    IPv4 Address. . . . . . . . . . . : 10.0.75.1

OS X El Capitan running Docker Version 17.03.0-ce-mac2, create an alias of IP 10.254.254.254 to your existing subnet mask.

sudo ifconfig en0 alias 10.254.254.254 255.255.255.0

If you want to remove the alias, use sudo ifconfig en0 -alias 10.254.254.254

Using git, clone the official docker WordPress image package. To avoid conflicts with the existing wordpress volume, create a build directory to clone the package into.

mkdir build

cd build

git clone https://github.com/docker-library/wordpress.git

Edit the build/wordpress/php5.6/apache/Dockerfile appending to the docker-php-ext-install instruction. For example, at the end of the line, add an escape character \ to escape a newline.

docker-php-ext-install gd mysqli opcache \

Add the following code which includes the newline escape at the end of each line, except for the last. This is so the docker-php-ext-install instruction can span multiple lines to install and configure Xdebug.

Dockerfile

docker-php-ext-install gd mysqli opcache \
&& pecl install xdebug \
&& echo "zend_extension=$(find /usr/local/lib/php/extensions/ -name xdebug.so)\n" >> /usr/local/etc/php/conf.d/xdebug.ini \
&& echo "xdebug.remote_enable=1\n" >> /usr/local/etc/php/conf.d/xdebug.ini \
&& echo "xdebug.remote_autostart=1\n" >> /usr/local/etc/php/conf.d/xdebug.ini \
&& echo "xdebug.remote_connect_back=0\n" >> /usr/local/etc/php/conf.d/xdebug.ini \
&& echo "xdebug.remote_host=10.0.75.1\n" >> /usr/local/etc/php/conf.d/xdebug.ini \
&& echo "xdebug.remote_port=9001\n" >> /usr/local/etc/php/conf.d/xdebug.ini \
&& echo "xdebug.idekey=REMOTE\n" >> /usr/local/etc/php/conf.d/xdebug.ini

For OS X, use xdebug.remote_host=10.254.254.254 in the Dockerfile.

Dockerfile reference: docs.docker.com/engine/reference/builder/

Build

Navigate to the folder where the updated Dockerfile is and tag the image build wpxdebug followed by a dot.

cd wordpress/php5.6/apache
    
docker build -t wpxdebug .

Once the build has completed, the output should contain a success message with the image ID, for example:

Successfully built 446ca7686815

Verify that the wpxdebug build exists.

docker images wpxdebug

Squash newly built layers into a single new layer using the –squash option. For example docker build --squash -t wpxdebug . Remove the unused layers after the build with docker image prune

Update the wp service in the docker compose file by replacing image: wordpress with image: wpxdebug. Additionally, create a custom php.ini file for overwriting various setting and add a volume for it. Everything else remains the same as before.

wp.yml

version: "2"
services:
  db:
    image: mariadb
    volumes:
      - mysql:/var/lib/mysql
    ports:
      - "8001:3306"
    environment:
      - MYSQL_ROOT_PASSWORD=secret
  phpmyadmin:
    image: phpmyadmin/phpmyadmin:latest
    ports:
      - "8002:80"
    links:
      - db:mysql
    environment:
      - MYSQL_ROOT_PASSWORD=secret
      - VIRTUAL_HOST=phpmyadmin.app
      - VIRTUAL_PORT=8002
  wp:
    image: wpxdebug
    volumes:
      - ./php/php.ini:/usr/local/etc/php/php.ini
      - ./wordpress:/var/www/html
    ports:
      - "8003:80"
    links:
      - db:mysql
    environment:
      - WORDPRESS_DB_PASSWORD=secret
      - VIRTUAL_HOST=wordpress.dev
      - VIRTUAL_PORT=8003
volumes:
  mysql:

php/php.ini

memory_limit = 128M
post_max_size = 32M
upload_max_filesize = 16M
max_execution_time = 300

VS Code has great support for PHP, add an adapter for Xdebug such as vscode-php-debug and we’re good to go. Open the local volume folder named wordpress which should be in the same folder as the docker compose wp.yml file.

After installing vscode-php-debug, the projects launch.json file needs to be updated to include the properties to map the files on the server to the local machine. Add the serverSourceRoot and localSourceRoot settings to the wordpress/.vscode/launch.json file. For example,

launch.json

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Listen for Xbebug",
            "type": "php",
            "request": "launch",
            "port": 9001,
            "serverSourceRoot": "/var/www/html",
            "localSourceRoot": "${workspaceRoot}"
        }, {
            "name": "Launch currently open script",
            "type": "php",
            "request": "launch",
            "program": "${file}",
            "cwd": "${fileDirname}",
            "port": 9001
        }
    ]
}

Set some breakpoints and reload wordpress.dev in the browser.