<?php

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;
            }

            throw new \ErrorException($message, 0, $severity, $file, $line);
        });

        set_exception_handler(static function (\Throwable $exception): void {
            // Security::reportThrowable journalise systématiquement le détail
            // côté serveur et ne le renvoie au client que si PTA_DEBUG est
            // explicitement activé. Par défaut, rien ne fuit.
            $payload = ['error' => 'Une erreur serveur est survenue.'];
            if (Security::debugEnabled()) {
                $payload['details'] = $exception->getMessage();
            }
            Security::reportThrowable($exception, 'Erreur API.');

            self::send(500, $payload);
        });
    }

    /**
     * É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;
    }
}