add php debugging

.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.

.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"]

.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

.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.

.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"
+            }
+        }
+    ]
+}

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

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.