From 339c0503bab9675d3c37734ba1902566f7791f24 Mon Sep 17 00:00:00 2001
From: Pier-Paolo Mammi <pierpaolo.mammi@unipr.it>
Date: Thu, 16 Jul 2026 12:18:53 +0200
Subject: [PATCH] add php debugging

---
 .agents/AGENTS.md               | 48 ++++++++++++++++++++++
 .docker/php/Dockerfile          | 15 +++++++
 .docker/php/xdebug.ini          |  9 ++++
 .github/copilot-instructions.md | 13 ++++++
 .vscode/launch.json             | 60 +++++++++++++++++++++++++++
 docker-compose.yml              | 17 ++++++++
 docs/debug-api-vscode-docker.md | 73 +++++++++++++++++++++++++++++++++
 7 files changed, 235 insertions(+)
 create mode 100644 .docker/php/Dockerfile
 create mode 100644 .docker/php/xdebug.ini
 create mode 100644 .github/copilot-instructions.md
 create mode 100644 .vscode/launch.json
 create mode 100644 docker-compose.yml
 create mode 100644 docs/debug-api-vscode-docker.md

diff --git a/.agents/AGENTS.md b/.agents/AGENTS.md
index e766a2c..e846d4e 100644
--- a/.agents/AGENTS.md
+++ b/.agents/AGENTS.md
@@ -23,3 +23,51 @@ Queste regole definiscono il comportamento per tutti gli sviluppi futuri su ques
 6. **Routing API e prefissi di versione**
    Le route devono essere registrate senza il prefisso `/api` e senza il prefisso di versione (es. usare `/users` invece di `/api/users` o `/api/v1/users`). Il router deve normalizzare i percorsi in ingresso rimuovendo il prefisso `/api` prima di confrontarli con le route registrate, così richieste come `/api/users` e `/api/v1/users` continuano a funzionare.
 
+---
+
+# Debug API PHP con VS Code e Docker
+
+Questa sezione descrive la procedura per fare debug delle API PHP servite da Docker in questa repository.
+
+## Passaggi
+
+1. Avvia il container Docker dalla root del progetto:
+   ```bash
+   docker compose up --build
+   ```
+
+2. Apri Visual Studio Code e vai su "Run and Debug".
+
+3. Seleziona la configurazione:
+   ```text
+   Debug PHP in Docker
+   ```
+
+4. Premi F5 per avviare il debugger.
+
+5. Imposta un breakpoint in un controller, ad esempio in:
+   ```text
+   src/Api/Controllers/V1/UsersController.php
+   ```
+
+6. Richiama l’endpoint tramite browser o curl:
+   ```bash
+   curl -H "XDEBUG_TRIGGER: 1" http://localhost:8000/api/users
+   ```
+
+## Nota
+
+Il container deve esporre:
+- porta `8000` per HTTP
+- porta `9003` per Xdebug
+
+Il progetto contiene già i file necessari per il debug:
+- `.docker/php/Dockerfile`
+- `docker-compose.yml`
+- `.vscode/launch.json`
+- `.vscode/settings.json`
+
+## Problemi comuni
+
+- Se VS Code non si ferma sul breakpoint, verifica che Xdebug sia abilitato nel container e che la configurazione `client_host` punti a `host.docker.internal`.
+- Se il container non si avvia, controlla che Docker Desktop sia in esecuzione.
diff --git a/.docker/php/Dockerfile b/.docker/php/Dockerfile
new file mode 100644
index 0000000..5a581e7
--- /dev/null
+++ b/.docker/php/Dockerfile
@@ -0,0 +1,15 @@
+FROM php:8.2-cli
+
+RUN pecl install xdebug \
+    && docker-php-ext-enable xdebug
+    #\
+    #&& echo 'xdebug.mode=debug' > /usr/local/etc/php/conf.d/docker-php-ext-xdebug.ini \
+    #&& echo 'xdebug.start_with_request=yes' >> /usr/local/etc/php/conf.d/docker-php-ext-xdebug.ini \
+    #&& echo 'xdebug.idekey=VSCODE' >> /usr/local/etc/php/conf.d/docker-php-ext-xdebug.ini \
+    #&& echo 'xdebug.client_port=9003' >> /usr/local/etc/php/conf.d/docker-php-ext-xdebug.ini \
+    #&& echo 'xdebug.client_host=host.docker.internal' >> /usr/local/etc/php/conf.d/docker-php-ext-xdebug.ini
+
+WORKDIR /app
+EXPOSE 8000 9003
+
+CMD ["php", "-S", "0.0.0.0:8000", "-t", "public", "public/index.php"]
diff --git a/.docker/php/xdebug.ini b/.docker/php/xdebug.ini
new file mode 100644
index 0000000..6511e14
--- /dev/null
+++ b/.docker/php/xdebug.ini
@@ -0,0 +1,9 @@
+zend_extension=/usr/local/lib/php/extensions/no-debug-non-zts-20220829/xdebug.so
+
+[xdebug]
+xdebug.mode=develop,debug
+xdebug.start_with_request=yes
+xdebug.client_host=host.docker.internal
+xdebug.client_port=9003
+xdebug.log_level=0
+xdebug.idekey=VSCODE
\ No newline at end of file
diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
new file mode 100644
index 0000000..0371607
--- /dev/null
+++ b/.github/copilot-instructions.md
@@ -0,0 +1,13 @@
+# Istruzioni per lo sviluppo di questa repository
+
+## Debug delle API PHP con Docker
+
+Quando si lavora su questa repository e si deve fare debug delle API PHP servite via Docker, usare il setup seguente:
+
+- avviare il container con `docker compose up --build`
+- usare la configurazione VS Code `Debug PHP in Docker`
+- mettere breakpoint nei controller sotto `src/Api/Controllers`
+- testare le richieste su `http://localhost:8000`
+- se il debugger non parte, usare `curl -H "XDEBUG_TRIGGER: 1" http://localhost:8000/api/users`
+
+Queste istruzioni valgono anche per eventuali problemi di routing o di esecuzione delle API.
diff --git a/.vscode/launch.json b/.vscode/launch.json
new file mode 100644
index 0000000..d5e635b
--- /dev/null
+++ b/.vscode/launch.json
@@ -0,0 +1,60 @@
+{
+    // 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": "Attach to Chrome",
+            "port": 9222,
+            "request": "attach",
+            "type": "chrome",
+            "webRoot": "${workspaceFolder}"
+        },
+
+        {
+            "name": "Listen for Xdebug (Docker)",
+            "type": "php",
+            "request": "launch",
+            "port": 9003,
+            "pathMappings": {
+                "/app": "${workspaceFolder}"
+            },
+            "log": true
+        },
+        {
+            "name": "Launch currently open script",
+            "type": "php",
+            "request": "launch",
+            "program": "${file}",
+            "cwd": "${fileDirname}",
+            "port": 0,
+            "runtimeArgs": [
+                "-dxdebug.start_with_request=yes"
+            ],
+            "env": {
+                "XDEBUG_MODE": "debug,develop",
+                "XDEBUG_CONFIG": "client_port=${port}"
+            }
+        },
+        {
+            "name": "Launch Built-in web server",
+            "type": "php",
+            "request": "launch",
+            "runtimeArgs": [
+                "-dxdebug.mode=debug",
+                "-dxdebug.start_with_request=yes",
+                "-S",
+                "localhost:0"
+            ],
+            "program": "",
+            "cwd": "${workspaceRoot}",
+            "port": 9003,
+            "serverReadyAction": {
+                "pattern": "Development Server \\(http://localhost:([0-9]+)\\) started",
+                "uriFormat": "http://localhost:%s",
+                "action": "openExternally"
+            }
+        }
+    ]
+}
\ No newline at end of file
diff --git a/docker-compose.yml b/docker-compose.yml
new file mode 100644
index 0000000..7fb5ab2
--- /dev/null
+++ b/docker-compose.yml
@@ -0,0 +1,17 @@
+services:
+  php-api:
+    build:
+      context: .
+      dockerfile: .docker/php/Dockerfile
+    container_name: elixforms-php-api
+    working_dir: /app
+    extra_hosts:
+      - "host.docker.internal:host-gateway"
+    ports:
+      - "8000:8000"
+    volumes:
+      - .:/app
+      - ./.docker/php/xdebug.ini:/usr/local/etc/php/conf.d/xdebug.ini
+    #environment:
+    #  XDEBUG_MODE: debug
+    #  XDEBUG_CONFIG: client_host=host.docker.internal client_port=9003 start_with_request=yes
diff --git a/docs/debug-api-vscode-docker.md b/docs/debug-api-vscode-docker.md
new file mode 100644
index 0000000..c6e17b9
--- /dev/null
+++ b/docs/debug-api-vscode-docker.md
@@ -0,0 +1,73 @@
+# Debug delle API PHP in VS Code con Docker
+
+Queste istruzioni permettono di fare debug delle API PHP servite con Docker direttamente da Visual Studio Code.
+
+## Prerequisiti
+
+- Docker Desktop installato e in esecuzione
+- Visual Studio Code
+- Estensione PHP per VS Code
+
+## 1. Avvia il container
+
+Dalla root del progetto esegui:
+
+```bash
+docker compose up --build
+```
+
+Il server PHP sarà disponibile su:
+
+```text
+http://localhost:8000
+```
+
+## 2. Avvia il debug in VS Code
+
+Apri la sezione Run and Debug e seleziona la configurazione:
+
+```text
+Debug PHP in Docker
+```
+
+Poi premi F5.
+
+## 3. Imposta un breakpoint
+
+Aggiungi un breakpoint in un controller, ad esempio in:
+
+```text
+src/Api/Controllers/V1/UsersController.php
+```
+
+Quindi richiama un endpoint come:
+
+```text
+http://localhost:8000/api/users
+```
+
+## 4. Se il debugger non parte
+
+Prova a inviare la richiesta con il trigger Xdebug:
+
+```bash
+curl -H "XDEBUG_TRIGGER: 1" http://localhost:8000/api/users
+```
+
+## 5. Configurazione attesa
+
+Il progetto contiene già:
+
+- un Dockerfile PHP con Xdebug
+- un file docker-compose.yml
+- una configurazione di avvio VS Code in .vscode/launch.json
+
+## 6. Nota importante
+
+Il server PHP viene eseguito con:
+
+```bash
+php -S 0.0.0.0:8000 -t public public/index.php
+```
+
+Questa modalità è adatta per il debug delle API HTTP del progetto.