docker/l3d#65 Add xdebug documentation

docs/docker/l3d/drupal.md

@@ -5,6 +5,8 @@ tags:
 ---
 # L3D and Drupal Projects
 
+## Introduction and overview
+
 We do provide a couple of project templates for Drupal projects out of the box:
 
 - [Drupal 8](/composer/project/d8)
@@ -175,3 +177,33 @@ DOCKER4DRUPAL_TRAEFIK_KEY=privkey.pem
 To update your Traefik configuration and restart the service, go to one of your
 projects in L3D and call `ahoy traefik rewrite` to get everything setup once and
 forever.
+
+## Using XDebug
+
+Debugging PHP can be a game changer in Drupal development. In the context of L3D
+in combination with the composer plugin [Docker4Drupal](/composer/plugin/d4d)
+this is provided out of the box and configured very easily. We describe the
+steps for PhpStorm, but other IDEs should be very similar.
+
+As XDebug comes with a performance hit, it is turned off by default. When you
+need it, simply call `ahoy debug on` in you L3D container of the project you
+want to debug and the scripts will reconfigure the PHP container and refresh
+it with a few seconds. When you've finished debugging, you may want to turn it
+off again with `ahoy debug off`.
+
+XDebug version 3 connects to port 9003 of your IDE and PhpStorm is preconfigured
+by default to list on that port.
+
+You can then just enable debugging in PhpStorm and wait for the first request
+which will prompt you to configure the details. Or you configure actively the
+debug configuration:
+
+![Screenshot](/files/screenshots/Screenshot from 2021-01-25 18-59-52.png)
+
+The name and the server name should both be called `Docker`. And the mapping
+needs to be configured from your project root directory on your host to the
+path `/var/www/html` in the container.
+
+With this setup, you can debug both web requests coming from the browser and
+CLI commands for PHP which is executed inside the PHP container like e.g.
+drush - all with the same setup.