Função headers_list() do PHP: Tudo o Que Você Precisa Saber

Toda resposta PHP carrega um conjunto de cabeçalhos HTTP — como Content-Type, Set-Cookie e quaisquer valores personalizados que você adicionar. A função headers_list() permite inspecionar esse conjunto de dentro do seu script: ela retorna os cabeçalhos que o PHP está prestes a enviar (ou já enviou) ao cliente. Isso é inestimável para depurar redirecionamentos, tipos de conteúdo e cookies antes de a resposta ser enviada.

Esta página aborda o que headers_list() retorna, quando esses cabeçalhos estão disponíveis, a diferença entre ela e headers_sent(), e padrões práticos de uso.

Sintaxe

headers_list(): array

headers_list() não recebe nenhum parâmetro e retorna um array indexado de strings. Cada string é uma linha de cabeçalho no exato formato em que será enviada, por exemplo Content-Type: text/html; charset=UTF-8. Se nenhum cabeçalho tiver sido definido ainda, você obtém um array vazio.

Um exemplo básico

A função reflete os cabeçalhos que o PHP planeja enviar no momento. Defina alguns com header() primeiro e, em seguida, liste-os:

<?php

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

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

Uma saída típica (o conjunto exato depende da sua configuração de PHP/servidor):

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

O PHP frequentemente adiciona cabeçalhos padrão por conta própria (como Content-Type e X-Powered-By) antes do seu código ser executado, portanto a lista pode conter entradas que você nunca definiu explicitamente.

Quando os cabeçalhos estão disponíveis?

headers_list() reflete apenas os cabeçalhos que o PHP mantém em seu buffer interno. Duas consequências importantes:

• Ela reporta os cabeçalhos independentemente de terem sido enviados ou não. Use-a em conjunto com headers_sent() quando precisar saber se o buffer já foi descarregado.
• Ela funciona somente no lado do servidor. Ela não retorna os cabeçalhos de requisição enviados pelo navegador — para isso, use getallheaders() ou a superglobal $_SERVER.

Verificando um cabeçalho específico

Uma tarefa comum é verificar se um determinado cabeçalho foi definido — por exemplo, confirmar se o Location de um redirecionamento está presente antes de depender dele:

<?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";

Saída:

Redirect header is set

stripos(..., 'Location:') === 0 faz a correspondência sem distinção de maiúsculas e minúsculas no início da linha, pois os nomes dos cabeçalhos não são sensíveis a maiúsculas e minúsculas.

headers_list() vs. funções relacionadas

Como headers_list() é somente leitura, é seguro chamá-la em qualquer ponto — ela nunca produz o aviso "headers already sent" que header() pode gerar.

Casos de uso comuns

• Depuração: exiba headers_list() durante o desenvolvimento para ver exatamente o que o servidor está enviando, incluindo cookies definidos por setcookie().
• Lógica condicional: decida se deve adicionar um cabeçalho apenas se ele ainda não estiver presente.
• Testes: verifique se um controlador produziu o Content-Type ou Cache-Control esperado.

Conclusão

headers_list() fornece um snapshot somente leitura dos cabeçalhos de resposta HTTP que o PHP pretende enviar. Use-a em conjunto com headers_sent() para verificar o momento do envio, header() para definir valores e header_remove() para limpá-los. Juntas, essas funções fornecem controle total sobre o cabeçalho da resposta antes que ela chegue ao navegador.

Prática