feat: enable php debugging for wp-cli commands

.docker/wp-cli/Dockerfile

@@ -0,0 +1,29 @@
+ARG PHP_VERSION
+
+FROM wordpress:cli-php${PHP_VERSION:-8.1}
+
+# Switch to root user to ensure we have the necessary permissions
+USER root
+
+RUN apk add --update linux-headers
+
+# Install Xdebug
+RUN apk --no-cache add pcre-dev ${PHPIZE_DEPS} \
+  && pecl install xdebug \
+  && docker-php-ext-enable xdebug \
+  && apk del pcre-dev ${PHPIZE_DEPS}
+
+# Configure Xdebug
+RUN { \
+    echo 'xdebug.mode=debug'; \
+    echo 'xdebug.start_with_request=yes'; \
+    echo 'xdebug.client_host=host.docker.internal'; \
+    echo 'xdebug.client_port=9003'; \
+    echo 'xdebug.log=/tmp/xdebug.log'; \
+} > /usr/local/etc/php/conf.d/docker-php-ext-xdebug.ini
+
+# Ensure the configuration is loaded
+RUN echo 'zend_extension=xdebug.so' >> /usr/local/etc/php/conf.d/docker-php-ext-xdebug.ini
+
+# Switch back to the default user (if necessary)
+USER www-data

README.md

@@ -109,9 +109,11 @@ the Usage section).
 
 ## How to Use Xdebug
 
-Xdebug is enabled by default. To use it with Visual Studio Code, you have to
-include `?XDEBUG_SESSION=TRUE` in the URL you are browsing, and you have to use
-this `launch.json` settings:
+Xdebug comes pre-installed and activated in the wp and cli containers, allowing
+debugging of website requests and WP-CLI commands.
+
+To use Xdebug with Visual Studio Code, you have to include `?XDEBUG_SESSION=TRUE`
+in the URL you are browsing, and you have to use this `launch.json` settings:
 
 ```JSON
 {
@@ -129,12 +131,23 @@ this `launch.json` settings:
   ]
 }
 ```
+As an alternative to the `?XDEBUG_SESSION=TRUE` parameter in the URL, you can use
+a browser extension like Xdebug Helper for [Chrome](https://chromewebstore.google.com/detail/xdebug-helper/eadndfjplgieldjbigjakmdgkmoaaaoc),
+[Firefox](https://addons.mozilla.org/en-US/firefox/addon/xdebug-helper-for-firefox/),
+[Edge](https://microsoftedge.microsoft.com/addons/detail/xdebug-helper/ggnngifabofaddiejjeagbaebkejomen)
+or [Xdebug Key for Safari](https://apps.apple.com/bg/app/xdebug-key/id1441712067?mt=12), 
+
+To initiate Xdebug for WP-CLI commands, you need to set an environment variable `XDEBUG_SESSION=true` inside
+the cli Docker container. E.g.
+```shell
+docker-compose run -e XDEBUG_SESSION=true --rm cli wp_cli_command_to_debug
+```
 
 You can enable/disable the Xdebug profiler by adding `profile` to the
 `XDEBUG_MODE` variable in `.env`, i.e. `XDEBUG_MODE=debug,profile`.
 
-By default, requests end up in the `./profiling` directory. The files begin with
-`cachegrind.out.` and are suffixed with the process ID.
+Profiling data files are, by default, stored in the ./profiling directory. These files are prefixed
+with cachegrind.out. and appended with the respective process ID.
 
 ## How to Use Mailhog
 

docker-compose.yml

@@ -59,7 +59,14 @@ services:
 
   cli:
     container_name: ${NAME}-cli
-    image: wordpress:cli-php${PHP_VERSION:-8.2}
+    build:
+      context: .
+      dockerfile: .docker/wp-cli/Dockerfile
+      args:
+        PHP_VERSION: ${PHP_VERSION:-8.1}
+    environment:
+      XDEBUG_MODE: develop,debug
+      XDEBUG_CONFIG: "client_host=host.docker.internal"
     volumes_from:
       - wp
     links: