Função PHP header_remove(): Tudo o que Você Precisa Saber

Toda resposta PHP carrega um conjunto de cabeçalhos HTTP — os metadados que o navegador lê antes de ver o conteúdo da sua página (tipo de conteúdo, regras de cache, cookies, redirecionamentos, entre outros). Às vezes você define um cabeçalho mais cedo em um script e depois decide que ele não deve ser enviado. header_remove() é a função integrada que retira um cabeçalho da resposta de saída antes que ela seja enviada ao cliente.

Este capítulo aborda a sintaxe, o parâmetro opcional, quando a remoção realmente funciona e os motivos mais comuns para utilizá-la.

O que header_remove() Faz

header_remove() exclui um cabeçalho que foi previamente enfileirado com header() (ou definido automaticamente pelo PHP) da lista de cabeçalhos que serão enviados com a resposta. Como o PHP armazena os cabeçalhos em buffer até que o corpo comece a ser transmitido, você pode adicioná-los e removê-los livremente até esse ponto.

A função opera na lista de cabeçalhos de saída, não nos cabeçalhos de requisição que seu script recebeu do navegador.

Sintaxe

header_remove(?string $name = null): void

• $name — o nome do cabeçalho a remover (sem distinção entre maiúsculas e minúsculas, sem os dois-pontos ou o valor), por exemplo "X-Powered-By". O parâmetro é opcional. Se você omiti-lo (ou passar null), todos os cabeçalhos definidos até o momento são removidos.
• Valor de retorno — nenhum (void).

Removendo um Único Cabeçalho

<?php

header("X-MyHeader: Hello World!");
header_remove("X-MyHeader");

Aqui o cabeçalho X-MyHeader é enfileirado e depois removido, portanto nunca chega ao navegador. O nome do cabeçalho é comparado sem distinção entre maiúsculas e minúsculas, então header_remove("x-myheader") removeria o mesmo cabeçalho.

Removendo Todos os Cabeçalhos

Chame a função sem argumento para limpar todos os cabeçalhos que você enfileirou:

<?php

header("X-First: 1");
header("X-Second: 2");

header_remove(); // both X-First and X-Second are dropped

Isso também limpa os cabeçalhos que o PHP adicionaria por conta própria (como X-Powered-By, se estiver habilitado), o que é um dos usos mais comuns no mundo real — remover a impressão digital do servidor antes que a saída comece.

Quando a Remoção Funciona

Os cabeçalhos só podem ser modificados antes que qualquer saída seja enviada. Assim que o primeiro byte do corpo sair do script — via echo, print, espaço em branco antes de <?php, ou um ?> de fechamento seguido de uma linha em branco — os cabeçalhos são descarregados e bloqueados.

Use headers_sent() para verificar se ainda é seguro alterar os cabeçalhos, e headers_list() para inspecionar os cabeçalhos atualmente enfileirados:

<?php

header("X-Debug: on");

if (!headers_sent()) {
    header_remove("X-Debug");
}

print_r(headers_list()); // X-Debug is no longer in the list

Se a saída já tiver começado, header_remove() não faz nada e o PHP emite um aviso de "headers already sent", assim como header() faria.

Casos de Uso Comuns

• Ocultar a impressão digital do servidor. Remova X-Powered-By para que as respostas não divulguem sua versão do PHP.
• Desfazer um cabeçalho condicional. Enfileire um cabeçalho de cache ou redirecionamento cedo e depois descarte-o se uma condição posterior mudar sua decisão.
• Resetar antes de um redirecionamento limpo. Limpe cabeçalhos indesejados antes de emitir um novo header("Location: ...").

Conclusão

header_remove() oferece controle preciso sobre a resposta HTTP de saída: passe um nome para remover um cabeçalho específico, ou chame-a sem argumento para limpar todos. Combine-a com headers_sent() e headers_list() para modificar cabeçalhos apenas enquanto ainda for permitido, e você poderá definir com confiança exatamente o que o navegador recebe.

Prática