From be0fe1ef7c3d13fc7f8c5ec842db96a4867f4fc8 Mon Sep 17 00:00:00 2001
From: k-37 <60838818+k-37@users.noreply.github.com>
Date: Mon, 11 Nov 2024 18:10:31 +0100
Subject: [PATCH] Add documentation about debugging with Visual Studio Code

References:

- https://gist.github.com/megahirt/e80086d1d029a7406e9eaec1fb1dcc9e
-
https://github.com/dunglas/symfony-docker/blob/6b37be14c98583e202cbbdec380c6e9e3103d2ab/docs/xdebug.md#debugging-with-xdebug-and-phpstorm
- https://blog.theodo.com/2019/07/vscode-php-development/#configure-xdebug-to-open-file-links-with-vs-code
---
 doc/editors.md | 46 ++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 46 insertions(+)

diff --git a/doc/editors.md b/doc/editors.md
index 0656207..ac1184e 100644
--- a/doc/editors.md
+++ b/doc/editors.md
@@ -19,3 +19,49 @@
 #### PHPStan
 
 - [Configuration and usage with PhpStorm](https://www.jetbrains.com/help/phpstorm/using-phpstan.html).
+
+## Visual Studio Code
+
+### Debugging
+
+#### Requirements
+
+- PHP Debug (`xdebug.php-debug`) extension for VSCode by *Xdebug*.
+
+#### Setup
+
+Create file `.vscode/launch.json` with contents:
+
+    {
+        // Use IntelliSense to learn about possible attributes.
+        // Hover to view descriptions of existing attributes.
+        // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
+        "version": "0.2.0",
+        "configurations": [
+            {
+                "name": "Listen for Xdebug",
+                "type": "php",
+                "request": "launch",
+                "port": 9003,
+                "pathMappings": {
+                    "/app": "${workspaceRoot}"
+                }
+            }
+        ]
+    }
+
+To make it possible to go directly to a line and file in VSCode by clicking on the filenames that Xdebug shows in stack traces in Symfony Profiler in `./etc/frankenphp/conf.d/20-app.dev.ini` comment out line starting with `xdebug.file_link_format=` and add this bellow it:
+
+    xdebug.file_link_format='vscode://file/%f:%l&/app><PATH_TO_APP_ON_HOST>'
+
+Path to app in container `/app` will be mapped to `<PATH_TO_APP_ON_HOST>` outside container.
+
+After making changes to `20-app.dev.ini` run `make restart`.
+
+#### Debug
+
+In VSCode [set breakpoint](https://code.visualstudio.com/docs/editor/debugging#_breakpoints), after that in menu click on `Run > Start Debugging`.
+
+Add the `XDEBUG_SESSION=1` query parameter to the URL of the page you want to debug (e.g. [http://localhost/?XDEBUG_SESSION=1](http://localhost/?XDEBUG_SESSION=1)), or use [other available triggers](https://xdebug.org/docs/step_debug#activate_debugger)
+
+Alternatively, you can use [the **Xdebug extension**](https://xdebug.org/docs/step_debug#browser-extensions) for your preferred web browser.