WordPress with xdebug enabled

This will create a container stack by the same name as the folder it sits in. Change project name in .env

project=project_name

at the top and change "kundenname" to something descriptive.

Dockerfile that pulls wordpress-apache and sets a couple of neccesary PHP ini-files and enables xdebug.

creates two containers wp (with the Dockerfile) and db for a standard MariaDB in a stack named earlier. The root of the WordPress content folder html/wp'content and the database data are bound to subfolders app to db respectively. The website can be accessed by

• localhost:8080/ → ./app as wp-content folder
• The rest of WordPress is irrelevant

By only exposing the `wp-content folder the rest of wordpress stays in the wp volume and is accessed at a slightly higher performance. But it cannot be debugged ofcourse another down side is that wp function signatures are not available and will lead to warnings when access from pluing/theme development. To alliviated the later add the wp -stubs.

If the complete WordPress installation should be available in the app folder adjust the compose.yaml file accordingly. Remember to also adjust the pathMappings in the launch.json file accordingly. See below to add stubs for WordPress to silence undefinied warnings.

First start Docker Desktop. When you're ready, start your application by running:

docker compose up --build.

in a terminal. If you have the Docker VSCode Extention installed it is even simpler. Open the compose.yaml and click

After this check the running state of the container in Docker Desktop.

If Docker Desktop or the docker daemon is not running you will see a confusing message:

If that happens start Docker Desktop and try again.

Setting up the database might take some time on slower hardware. Make sure that activity in the docker has died down.

Two extension are super handy:

1. Container Tools (previous Docker)
2. SQL-Tools for direct database access
3. PHP Profiler, to test what took so long
4. PHP Debug, to troubleshoot and step debug

The last two are only needed if one does theme or plugin development. Debugging / Profiling also needs a browser xdebug plugin. Watch the /logs folder for apache and xdebug logs. Make sure to set the proper setting in xdebug.ini and reboot the web server. Also check the section on launch.json

Normally you won't need database access from outside so the db server is not bridged. If you do need access add a port mapping in the db service and restart the container.

• Install xdebug extension

Tje launch.json file inludes the proper section to map the app folder to wp-content allowing debugging themes and plugins.

"pathMappings": {
    "/var/www/html/wp-content": "${workspaceFolder}/app"
}

The composer.json file (not to be confused with th compose.yaml file) includes settings to install the stubs in vendor/ folder. Run composer install to get the stubs. To make sure VScode uses them add this to the /.vscode.settings.json

{
    "intelephense.environment.includePaths": [
        "vendor/php-stubs/wordpress-stubs",
        "vendor/php-stubs/acf-pro-stubs",
        "app/plugins/elementor"
    ],
    "intelephense.files.exclude": [
        "**/.git/**",
        "**/node_modules/**",
        "app/plugins/!(elementor)/**"
    ],
}

Migrate with any standard WP backup or migration tool.

Currently the database is created in it own volume. If the project should be transportable change the db volume mapping in db in compose.yaml from

    volumes:
      - db:/var/lib/mysql

to

    volumes:
      - ./db:/var/lib/mysql

In that case the database is created as part of the project folder. As all key ingredients sit on in the file system, moving or copying the project is easy. Zip the project including app and db folders and unzip it somewhere else;. Make sure to shutdown the database first.