Ajout des commentaires dans le code

app/Core/PdfResponse.php

@@ -4,8 +4,24 @@ declare(strict_types=1);
 
 namespace App\Core;
 
+/**
+ * Émission d'un PDF généré par les services de app/Services/.
+ *
+ * Les points d'entrée PDF n'appellent PAS JsonResponse::bootstrap() : ils
+ * produisent un flux binaire, et un gestionnaire d'erreur qui écrirait du JSON
+ * au milieu corromprait le document.
+ */
 final class PdfResponse
 {
+    /**
+     * Envoie le document en affichage direct dans le navigateur, puis TERMINE
+     * le script.
+     *
+     * @param string $content  Octets du PDF déjà assemblé.
+     * @param string $filename Nom proposé ; il est assaini avant d'atterrir dans
+     *                         l'en-tête Content-Disposition, où un guillemet ou
+     *                         un retour ligne permettrait une injection d'en-tête.
+     */
     public static function inline(string $content, string $filename): void
     {
         $safeFilename = preg_replace('/[^A-Za-z0-9._-]+/', '_', $filename) ?: 'planning.pdf';
@@ -17,6 +33,8 @@ final class PdfResponse
             header('Content-Type: application/pdf');
             header('Content-Disposition: inline; filename="' . $safeFilename . '"');
             header('Content-Length: ' . strlen($content));
+            // Un planning peut être revalidé d'une minute à l'autre : on interdit
+            // au navigateur de resservir une version périmée.
             header('Cache-Control: private, max-age=0, must-revalidate');
             header('Pragma: public');
         }