From 6a7f12d75fcd3e43663e8319ba68b5118d5b8091 Mon Sep 17 00:00:00 2001
From: Danny <daniel@winningsoftware.co.uk>
Date: Thu, 24 Apr 2025 13:48:37 +0100
Subject: [PATCH] Update debugging page

---
 Debugging.md | 65 +++++++++++++++++++++++++++++++++++++---------------
 1 file changed, 46 insertions(+), 19 deletions(-)

diff --git a/Debugging.md b/Debugging.md
index 4a3c652..a4a57ab 100644
--- a/Debugging.md
+++ b/Debugging.md
@@ -1,19 +1,35 @@
-# XDebug
+# Debugging with Xdebug
+Loom Spinner PHP environments include **Xdebug** by default, making it easy to set up step debugging in your preferred IDE.
+## Disabling Xdebug
+To disable Xdebug for a new environment:
+- Pass the `--disable-xdebug` option to `spin:up`
+- **Or** set
+``` yaml
+  options:
+    environment:
+      php:
+        xdebug: false
+```
+in your project’s before building the environment `spinner.yaml`
 
-By default, your PHP container includes XDebug. This can be disabled for new environments by passing the 
-`--disable-xdebug` option to the `spin:up` command, or by setting `options.environment.php.xdebug: false` in your
-projects `spinner.yaml` file.
+> Changes require destroying/rebuilding your environment (see [Configuration](Configuration)). **Note:**
+>
 
-# Server Settings
+## Configuring Your IDE for Debugging
 
-The following instructions are for PHPStorm, I have not tested this with other IDE's, however the settings table should
-be fairly universal.
+The following instructions use PhpStorm, but similar settings apply in other IDEs.
 
-## Server Configuration
+### 1. Configure PHP Server
 
-- `File` -> `Settings`
-- `PHP` -> `Servers` -> `+`
-- Give your server a name and use the values shown below.
+1. **Go to:** `File` > `Settings` > `PHP` > `Servers`
+2. **Add a new server:**
+    - **Name:** (any, e.g. `Loom Spinner`)
+    - **Host:** `127.0.0.1`
+    - **Port:**
+      Use the **local port** your PHP container exposes (e.g., if `52033:9003` appears in `docker ps`, use `52033`)
+    - **Debugger:** Xdebug
+    - **Use path mappings:** ✅ (Enabled)
+        - Map your **project root** to `/var/www/html`
 
 | Setting                 | Value                                                                                                          |
 |-------------------------|----------------------------------------------------------------------------------------------------------------|
@@ -24,13 +40,24 @@ be fairly universal.
 | File/Directory          | Select **your project root**                                                                                   |
 | Absolute path on server | /var/www/html                                                                                                  |
 
-## Remote Debugger
+### 2. Set Up Remote Debugging
 
-- `Run` -> `Edit Configurations`
-- `+` -> `PHP Remote Debug`
-- Give it a name
-- Use the server you created before
-- Use **SPINNER** as IDE key
+1. **Go to:** `Run` > `Edit Configurations`
+2. **Add New Configuration:**
+    - Select **PHP Remote Debug**
+    - Assign a name (e.g., `Debug with Loom`)
+    - Choose the server you just created
+    - Set **IDE key**: `SPINNER`
 
-Make sure you start listening when you want to debug by clicking the little bug icon in the top right (by default) in 
-PHPStorm.
\ No newline at end of file
+### 3. Start Listening for Debug Connections
+
+- Click the debug (bug) icon in your IDE to start listening for incoming debug connections.
+- Set breakpoints in your code as needed.
+
+## Notes
+
+- The IDE key must be set to `SPINNER` for remote debugging.
+- The local port used by the PHP container can be found via `docker ps`.
+- Make sure Docker is running and your environment is active.
+
+For detailed tips, troubleshooting, or more advanced setup, consult your IDE's Xdebug documentation.