Ajout des commentaires dans le code

app/Core/JsonResponse.php

@@ -4,15 +4,35 @@ declare(strict_types=1);
 
 namespace App\Core;
 
+/**
+ * Sortie JSON des endpoints d'API.
+ *
+ * Le JavaScript de PTA refuse toute réponse qui n'est pas du JSON : une notice
+ * PHP ou une page d'erreur HTML se traduirait côté client par un message
+ * incompréhensible. bootstrap() garantit donc que même un warning ou une
+ * exception non rattrapée ressort en JSON.
+ *
+ * Les endpoints PDF sont la seule exception : ils émettent des octets binaires
+ * et n'appellent volontairement pas bootstrap() (voir PdfResponse).
+ */
 final class JsonResponse
 {
+    /**
+     * Installe les gestionnaires d'erreur/exception qui convertissent tout
+     * incident en réponse JSON 500. À appeler en toute première instruction du
+     * point d'entrée, avant même l'ouverture de la connexion PDO.
+     */
     public static function bootstrap(): void
     {
         ini_set('display_errors', '0');
         ini_set('html_errors', '0');
         error_reporting(E_ALL);
 
+        // Les warnings/notices deviennent des ErrorException : elles remontent
+        // ainsi au gestionnaire d'exception ci-dessous au lieu de polluer la
+        // sortie avec du HTML qui casserait le JSON.
         set_error_handler(static function (int $severity, string $message, string $file, int $line): bool {
+            // Respecte @ et error_reporting() : on laisse alors PHP gérer.
             if (!(error_reporting() & $severity)) {
                 return false;
             }
@@ -34,15 +54,27 @@ final class JsonResponse
         });
     }
 
+    /**
+     * Émet la réponse JSON et TERMINE le script.
+     *
+     * Ce exit final est ce qui permet aux gardes (Access, Csrf, Request) de
+     * s'écrire en une ligne sans que l'appelant ait à tester leur retour.
+     *
+     * @param int                  $status  Code HTTP (200, 403, 409, 422, 500…).
+     * @param array<string, mixed> $payload Corps sérialisé en JSON.
+     */
     public static function send(int $status, array $payload): void
     {
         if (!headers_sent()) {
             header('Content-Type: application/json; charset=utf-8');
             header('X-Content-Type-Options: nosniff');
+            // Les réponses dépendent du rôle en session : jamais de cache partagé.
             header('Cache-Control: no-store');
         }
 
         http_response_code($status);
+        // UNESCAPED_UNICODE garde les accents lisibles ; INVALID_UTF8_SUBSTITUTE
+        // évite qu'une donnée mal encodée en base fasse échouer tout l'encodage.
         echo json_encode($payload, JSON_UNESCAPED_UNICODE | JSON_INVALID_UTF8_SUBSTITUTE);
         exit;
     }