From 2e0a1b991caee424280ae351657bad7f7553040e Mon Sep 17 00:00:00 2001
From: Pier-Paolo Mammi <pierpaolo.mammi@unipr.it>
Date: Thu, 16 Jul 2026 15:28:03 +0200
Subject: [PATCH] add docs for CORS management

---
 docs/CORS.md | 33 ++++++++++++++++++++++-----------
 1 file changed, 22 insertions(+), 11 deletions(-)

diff --git a/docs/CORS.md b/docs/CORS.md
index 1de7232..8b9a8ba 100644
--- a/docs/CORS.md
+++ b/docs/CORS.md
@@ -7,12 +7,15 @@ This API now includes comprehensive CORS (Cross-Origin Resource Sharing) managem
 ## How It Works
 
 ### Automatic CORS Header Application
+
 All API responses automatically include CORS headers when CORS is enabled. This allows web applications from configured origins to access your API.
 
 ### Preflight Request Handling
+
 The API automatically handles preflight OPTIONS requests (sent by browsers before actual requests to CORS-protected resources). These are handled with a 204 No Content response.
 
 ### Origin Validation
+
 Only requests from configured allowed origins are accepted. Requests from unauthorized origins are rejected.
 
 ## Configuration
@@ -36,19 +39,20 @@ Edit `config/config.php` to configure CORS:
 
 ## Configuration Options
 
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `enabled` | bool | `true` | Enable or disable CORS |
-| `allowed_origins` | array | `[]` | List of domains allowed to access the API. Use `'*'` to allow all (NOT recommended) |
-| `allowed_methods` | array | `GET, POST, PUT, DELETE, PATCH, OPTIONS` | HTTP methods allowed |
-| `allowed_headers` | array | `Content-Type, Authorization, X-Requested-With, Accept` | Headers allowed in requests |
-| `exposed_headers` | array | `Content-Length, X-JSON-Response-Code` | Headers exposed to the client |
-| `allow_credentials` | bool | `false` | Allow credentials (cookies, auth) in requests |
-| `max_age` | int | `86400` | Browser cache time for preflight (seconds) |
+| Option              | Type  | Default                                                 | Description                                                                         |
+| ------------------- | ----- | ------------------------------------------------------- | ----------------------------------------------------------------------------------- |
+| `enabled`           | bool  | `true`                                                  | Enable or disable CORS                                                              |
+| `allowed_origins`   | array | `[]`                                                    | List of domains allowed to access the API. Use `'*'` to allow all (NOT recommended) |
+| `allowed_methods`   | array | `GET, POST, PUT, DELETE, PATCH, OPTIONS`                | HTTP methods allowed                                                                |
+| `allowed_headers`   | array | `Content-Type, Authorization, X-Requested-With, Accept` | Headers allowed in requests                                                         |
+| `exposed_headers`   | array | `Content-Length, X-JSON-Response-Code`                  | Headers exposed to the client                                                       |
+| `allow_credentials` | bool  | `false`                                                 | Allow credentials (cookies, auth) in requests                                       |
+| `max_age`           | int   | `86400`                                                 | Browser cache time for preflight (seconds)                                          |
 
 ## Setup for Different Environments
 
 ### Development
+
 ```php
 'cors' => [
     'enabled' => true,
@@ -63,6 +67,7 @@ Edit `config/config.php` to configure CORS:
 ```
 
 ### Production
+
 ```php
 'cors' => [
     'enabled' => true,
@@ -76,6 +81,7 @@ Edit `config/config.php` to configure CORS:
 ```
 
 ### Allow All Origins (NOT RECOMMENDED for Production)
+
 ```php
 'cors' => [
     'enabled' => true,
@@ -88,7 +94,7 @@ Edit `config/config.php` to configure CORS:
 
 When making cross-origin requests with certain headers or methods (like PUT or DELETE), browsers automatically send a preflight OPTIONS request. The API handles these automatically:
 
-```
+```text
 Browser sends: OPTIONS /api/resource
 API responds: 204 No Content + CORS headers
 Browser sees: Request is allowed, proceeds with actual request
@@ -97,6 +103,7 @@ Browser sees: Request is allowed, proceeds with actual request
 ## Testing CORS
 
 ### Using curl
+
 ```bash
 # Test CORS with curl
 curl -H "Origin: http://localhost:3000" \
@@ -107,7 +114,8 @@ curl -H "Origin: http://localhost:3000" \
 ```
 
 ### Expected Response Headers
-```
+
+```text
 HTTP/1.1 204 No Content
 Access-Control-Allow-Origin: http://localhost:3000
 Access-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS
@@ -149,16 +157,19 @@ if ($corsManager->isPreflightRequest()) {
 ## Troubleshooting
 
 ### Preflight request fails
+
 - Check that the origin in the request matches one in `allowed_origins`
 - Verify CORS is enabled in config
 - Check browser console for CORS error messages
 
 ### Missing CORS headers in response
+
 - Ensure CORS is enabled: `'enabled' => true`
 - Verify the requesting origin is in `allowed_origins`
 - Check that `CorsManager` is properly initialized in the container
 
 ### "No Access-Control-Allow-Origin header"
+
 - Browser origin is not in `allowed_origins`
 - Add the origin or use `'*'` (only for development)