Update debugging.md (#1323)

Author: brettins

distribution/debugging.md

@@ -43,12 +43,13 @@ services:
       # See https://docs.docker.com/docker-for-mac/networking/#i-want-to-connect-from-a-container-to-a-service-on-the-host
       # See https://github.com/docker/for-linux/issues/264
       # The `remote_host` below may optionally be replaced with `remote_connect_back`
+      # XDEBUG_MODE required for step debugging
+      XDEBUG_MODE: debug
+      # default port for Xdebug 3 is 9003
+      # idekey=VSCODE if you are debugging with VSCode
       XDEBUG_CONFIG: >-
-        remote_enable=1
-        remote_host=host.docker.internal
-        remote_connect_back=1
-        remote_port=9000
-        idekey=PHPSTORM
+        client_host=host.docker.internal
+        idekey=PHPSTORM 
       # This should correspond to the server declared in PHPStorm `Preferences | Languages & Frameworks | PHP | Servers`
       # Then PHPStorm will use the corresponding path mappings
       PHP_IDE_CONFIG: serverName=api-platform
@@ -61,13 +62,34 @@ Note for Mac environments use the following:
         remote_enable=1
         remote_host=docker.for.mac.localhost
         remote_connect_back=0
-        remote_port=9000
+        remote_port=9003
         idekey=PHPSTORM
         remote_autostart=1
         remote_mode=req
         remote_handler=dbgp
 ```
 
+In VSCode, alongside the default PHP configuration in `launch.json`, you'll need path mappings for the Docker image.
+```json
+{
+    "version": "0.2.0",
+    "configurations": [
+        {
+            "name": "Listen for Xdebug",
+            "type": "php",
+            "request": "launch",
+            "port": 9003,
+            "log": true,
+            "pathMappings": {
+                "/srv/api": "${workspaceFolder}/api"
+            },
+        },
+    ]
+}
+```
+
+Note: For Linux environments, the `client_host` setting of `host.docker.internal` will not work, you will need the actual local IP address of your computer.
+
 ## Troubleshooting
 
 Inspect the installation with the following command. The requested Xdebug