Función headers_list() de PHP: Todo lo que necesitas saber

Cada respuesta PHP lleva un conjunto de cabeceras HTTP — cosas como Content-Type, Set-Cookie y cualquier valor personalizado que añadas. La función headers_list() te permite inspeccionar ese conjunto desde dentro de tu script: devuelve las cabeceras que PHP está a punto de enviar (o ya ha enviado) al cliente. Esto es invaluable para depurar redirecciones, tipos de contenido y cookies antes de que la respuesta salga.

Esta página cubre qué devuelve headers_list(), cuándo existen realmente esas cabeceras, la diferencia entre esta función y headers_sent(), y patrones prácticos para usarla.

Sintaxis

headers_list(): array

headers_list() no toma ningún parámetro y devuelve un array indexado de cadenas. Cada cadena es una línea de cabecera única en la forma exacta en que será enviada, por ejemplo Content-Type: text/html; charset=UTF-8. Si aún no se han establecido cabeceras, obtienes un array vacío.

Un ejemplo básico

La función refleja las cabeceras que PHP planea enviar actualmente. Establece algunas con header() primero y luego listarlas:

<?php

header('Content-Type: application/json');
header('X-Powered-By: w3docs');

$headers = headers_list();
foreach ($headers as $header) {
    echo $header, "\n";
}

Una salida típica (el conjunto exacto depende de tu configuración de PHP/servidor):

Content-Type: application/json
X-Powered-By: w3docs

PHP a menudo añade cabeceras predeterminadas propias (como Content-Type y X-Powered-By) antes de que se ejecute tu código, por lo que la lista puede contener entradas que nunca estableciste explícitamente.

¿Cuándo están disponibles las cabeceras?

headers_list() solo refleja las cabeceras que PHP mantiene en su búfer interno. Hay dos consecuencias importantes:

• Reporta las cabeceras independientemente de si han sido enviadas o no. Úsala junto con headers_sent() cuando necesites saber si el búfer ya fue vaciado.
• Se ejecuta solo en el lado del servidor. No devuelve las cabeceras de solicitud que el navegador te envió — para eso usa getallheaders() o la superglobal $_SERVER.

Verificar una cabecera específica

Una tarea común es verificar que se estableció una cabecera concreta — por ejemplo, confirmar que la Location de una redirección está presente antes de depender de ella:

<?php

header('Location: /dashboard');

$hasLocation = false;
foreach (headers_list() as $header) {
    if (stripos($header, 'Location:') === 0) {
        $hasLocation = true;
        break;
    }
}

echo $hasLocation ? "Redirect header is set\n" : "No redirect header\n";

Salida:

Redirect header is set

stripos(..., 'Location:') === 0 coincide sin distinción de mayúsculas/minúsculas al inicio de la línea, ya que los nombres de cabecera no distinguen entre mayúsculas y minúsculas.

headers_list() frente a funciones relacionadas

Como headers_list() es de solo lectura, es seguro llamarla en cualquier momento — nunca produce la advertencia "headers already sent" que puede generar header().

Casos de uso comunes

• Depuración: vuelca headers_list() durante el desarrollo para ver exactamente qué está enviando el servidor, incluidas las cookies establecidas por setcookie().
• Lógica condicional: decide si añadir una cabecera solo si aún no está presente.
• Pruebas: verifica que un controlador produjo el Content-Type o Cache-Control esperado.

Conclusión

headers_list() te da una instantánea de solo lectura de las cabeceras de respuesta HTTP que PHP tiene previsto enviar. Combínala con headers_sent() para comprobar el momento, header() para establecer valores, y header_remove() para eliminarlos. Juntas, estas funciones te dan control total sobre la cabecera de respuesta antes de que llegue al navegador.

Práctica