Tema 12 · Control de Errores

12. Manejo Global de Excepciones y Errores: Respuestas JSON sin Fugas de Información

Implementa set_exception_handler y set_error_handler para atrapar cualquier fallo no controlado y retornar JSON limpio sin exponer contraseñas ni trazas de código.

El Peligro de las Trazas de Error HTML (Fugas de Información)

Por defecto, cuando ocurre una excepción no capturada en PHP (por ejemplo una falla de PDO con la base de datos), el motor imprime una traza de error en formato HTML estándar o texto plano.

En una API RESTful esto es desastroso por dos razones:

  1. Ruptura del Cliente: Las aplicaciones móviles y SPAs intentan parsear JSON y reciben un error SyntaxError: Unexpected token < in JSON al encontrarse con etiquetas HTML.
  2. Grave Brecha de Seguridad (Information Disclosure): Las trazas de PHP (stack traces) exponen nombres de tablas, usuarios de base de datos, contraseñas en variables de entorno y rutas internas de archivos del servidor VPS.

Manejadores Globales en PHP: set_exception_handler

En el bootstrap de nuestra API debemos registrar manejadores globales que intercepten cualquier excepción o error de PHP y garanticen que la salida sea siempre un JSON limpio con HTTP 500, registrando el error detallado únicamente en el log interno del servidor.

⚡ Configuración de Manejador Global de Errores en JSON

Script de captura global para evitar fugas de información en entornos de producción:

error_handler.php
Solo lectura
<?php
declare(strict_types=1);

// En producción: jamás mostrar errores crudos en pantalla
ini_set('display_errors', '0');
ini_set('display_startup_errors', '0');
error_reporting(E_ALL);

// 1. Manejador de Errores Nativos de PHP (Warnings, Notices)
set_error_handler(function (int $nivel, string $mensaje, string $archivo, int $linea): bool {
    error_log("[ERROR PHP] $mensaje en $archivo:$linea");
    // Convertir a ErrorException para atraparlo en el bloque de excepciones
    throw new ErrorException($mensaje, 0, $nivel, $archivo, $linea);
});

// 2. Manejador Global de Excepciones No Atrapadas
set_exception_handler(function (Throwable $e): void {
    // Registrar la traza completa de forma segura en el log del servidor
    error_log(sprintf(
        "[EXCEPCIÓN API] %s en %s:%d\nTraza:\n%s",
        $e->getMessage(),
        $e->getFile(),
        $e->getLine(),
        $e->getTraceAsString()
    ));

    // Determinar si estamos en desarrollo o producción
    $esDesarrollo = (getenv('APP_ENV') === 'development');

    http_response_code(500);
    header('Content-Type: application/json; charset=utf-8');

    $respuesta = [
        'status'  => 'error',
        'code'    => 500,
        'message' => 'Ocurrió un error interno en el servidor.',
    ];

    if ($esDesarrollo) {
        $respuesta['debug'] = [
            'error'   => $e->getMessage(),
            'archivo' => $e->getFile(),
            'linea'   => $e->getLine(),
        ];
    }

    echo json_encode($respuesta, JSON_UNESCAPED_UNICODE);
    exit;
});
🧠
Mini-Quiz de Retención
Comprueba tu comprensión antes de pasar a la siguiente lección
1 Pregunta
Pregunta 1
¿Por qué nunca se debe activar "display_errors = 1" en el servidor de producción de una API REST?
🦉
¿Tienes dudas con este tema?
Sócrates AI puede darte analogías y explicarte este código paso a paso.

🚀 ¿Quieres dominar APIs RESTful con PHP Puro, JSON & JWT y crear proyectos reales?

Aprende arquitectura limpia, desarrollo web moderno, buenas prácticas y despliegue en producción con nuestro Bootcamp Fullstack Developer con mentorías en vivo.

🏛️ Autoría y Propiedad Intelectual: Obra educativa original de Juan Sebastián Amador para Kilopolis Academia, estructurada sobre las especificaciones y estándares abiertos del W3C, el estándar vivo de WHATWG y la documentación oficial de código abierto. © Todos los derechos reservados.