So, finally I got some time to dive into a long-standing Topic w.r. to web Development, especially Grav Plugins with PHP/Symfony - 18 Years after my last Article on the very same Topic.
My usual Method followed the Procedures outlined in the official Grav Documentation, including Testing & Debugging, which worked ok so far, but I always knew there is something better: Xdebug.
However, I did not get the clue so far, how to best include this in my usual Toolchain, which has been Kdevelop, Docker and Sitecopy on Debian Buster, so far.
Especially, there seemed to be no way to integrate Xdebug with the IDE (Kdevelop), although I knew there must have been a way to do this, at least, in the past. But then, over the last Months, I got more and more used to Visual Studio Code at my Workplace, and, despite this beeing a Microsoft Product, I began to like it . Then, as I saw this is also available on Linux as a native Version, I began to use this more and more also on my favourite Platform: Debian (Buster).
This was also the Time to think again about Xdebug Integration, as I found more and more articles on the Net promoting this.
So, finally, I bit the bullet and gave it a try.
The first Steps seemed to be promising, as it turned out to not be too hard to:

But, as always, there are Pitfalls:
Most descriptions on the net refer to configuring VS Code to work with Docker on Windows, which seems to be easier than on Linux, as the most Tutorials out there describe how to connect VS Code to an Xdebug Instance running on localhost via XAMPP, which is NOT true for Xdebug inside Docker.
For that use case, most Docs refer to using xdebug.client_host=host.docker.internal in xdebug.ini, but unfortunately, this works only on Windows & Mac, not on Linux.
Finally, I found the relevant Hints in this Article, where in the comments, there is also a rudimentary Bash Script that detects the IP address of the Docker Host and writes it as host.docker.internal to /etc/hosts in the Docker Image.
So, after having figured this out, I put together all the pieces and finally got it all working, the result is a modified Clone of the official Grav Docker Project on GitHub.
In short, the Operation is as follows:

  • the original Dockerfile has been modified to additionally install Xdebug, iputils-ping and iproute2
  • the script entrypoint.sh is copied into the Docker Image, it will detect the Docker host and add the appropriate entry to /etc/hosts
  • this is then started just before cron and the webserver
  • the configuration file for xdebug, xdebug.ini, is mirrored from the local storage into the Docker Instance via docker-compose.yml
  • this way, it can be modified locally without having to build a new docker image
  • the VSCODE launch configuration is in .vscode/launch.json and is used to point to the grav files inside the docker Instance

This Setup has been tested and proved to work on Debian Buster + Docker + Grav + VS Code.
No warranty, however, for this to work in other scenarios - so, as always: YMMV .