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

Toda resposta HTTP enviada por um servidor web tem duas partes: um conjunto de cabeçalhos (metadados como o tipo de conteúdo, regras de cache e código de status) seguido pelo corpo da resposta (o HTML, JSON, imagem ou arquivo que o navegador recebe). A função header() do PHP permite que você escreva esses cabeçalhos a partir do seu script — para redirecionar usuários, servir downloads, definir o tipo de conteúdo, controlar o cache e enviar códigos de status personalizados.

Este guia cobre a sintaxe e os parâmetros de header(), a regra que quase todos tropeçam (o erro "headers already sent") e as receitas mais comuns do mundo real.

O que é a Função header()?

header() é uma função embutida do PHP que envia um cabeçalho HTTP bruto ao cliente. Um cabeçalho é uma única linha como Content-Type: text/html ou Location: /login que o navegador lê antes do corpo da página. Como os cabeçalhos vêm primeiro na resposta, header() só funciona enquanto o PHP ainda está construindo essa seção de cabeçalhos — veja a regra "headers already sent" abaixo.

Sintaxe e Parâmetros

header(string $header, bool $replace = true, int $response_code = 0): void

A função não retorna nada (void). Ela não informa se o cabeçalho foi aceito — se a saída já foi enviada, ela emite um aviso em vez disso.

Definindo um cabeçalho

O uso mais simples é declarar que tipo de conteúdo a resposta contém. Isso é essencial quando seu script retorna JSON, XML, texto simples ou um arquivo em vez de HTML:

<?php

header("Content-Type: application/json");

echo json_encode(["status" => "ok", "id" => 42]);

O cabeçalho Content-Type diz ao navegador para tratar o corpo como JSON, então ele analisa {"status":"ok","id":42} como dados em vez de renderizá-lo como uma página web.

A regra "headers already sent"

Esta é a coisa mais importante a saber sobre header(): ela deve ser chamada antes de qualquer saída deixar seu script. A saída inclui HTML, echo/print, var_dump(), e até mesmo um espaço ou linha em branco antes da tag de abertura <?php. Assim que um byte do corpo for enviado, a seção de cabeçalhos é fechada e o PHP emite:

Warning: Cannot modify header information - headers already sent

Você tem duas formas de evitar isso:

<?php

// 1. Check first — useful when a header is optional
if (!headers_sent()) {
    header("X-Powered-By: MyApp");
}

// 2. Buffer output so nothing is flushed until you choose to
ob_start();                 // capture everything that gets echoed
echo "page content...";
header("X-Cache: MISS");    // still works — body is held in the buffer
ob_end_flush();             // now send headers + buffered body together

Uma causa comum é um editor salvando o arquivo com um BOM UTF-8 ou uma nova linha após ?>. Omitir a tag de fechamento ?> inteiramente em arquivos PHP puros é a forma recomendada de evitar isso.

Casos de uso comuns

Redirecionando para outra URL

Envie um cabeçalho Location, depois pare o script para que nenhum código adicional seja executado:

<?php

header("Location: https://example.com/login");
exit;   // always exit after a redirect

Por padrão, este é um redirecionamento 302 Found (temporário). Para uma mudança permanente, passe 301 como código de status para que os mecanismos de busca atualizem seu índice:

<?php

// 301 Moved Permanently
header("Location: https://example.com/new-page", true, 301);
exit;

Enviando um código de status personalizado

Você pode definir um status sem redirecionar — para uma API retornando "não encontrado", por exemplo:

<?php

header("HTTP/1.1 404 Not Found");
// or, more portably:
header("Status: 404 Not Found", true, 404);

echo "Resource not found";

Para códigos de status especificamente, a função dedicada http_response_code() é mais clara e fácil de ler.

Forçando o download de um arquivo

Combine Content-Type com Content-Disposition: attachment para fazer o navegador salvar o arquivo em vez de exibi-lo:

<?php

$file = "report.pdf";

header("Content-Type: application/pdf");
header("Content-Disposition: attachment; filename=\"$file\"");
header("Content-Length: " . filesize($file));

readfile($file);   // stream the file to the client
exit;

Veja readfile() para transmitir o conteúdo do arquivo para a saída.

Controlando o cache do navegador

Os cabeçalhos permitem que você diga ao navegador se (e por quanto tempo) ele pode reutilizar uma resposta:

<?php

// Tell the browser never to cache this response
header("Cache-Control: no-store, no-cache, must-revalidate");
header("Expires: 0");

Enviando múltiplos cabeçalhos com o mesmo nome

A maioria dos cabeçalhos substitui qualquer um anterior com o mesmo nome. Defina o segundo argumento como false quando você genuinamente precisar de mais de um (raro, mas válido para alguns cabeçalhos):

<?php

header("X-Sample: first");
header("X-Sample: second", false);   // both X-Sample headers are sent

Funções relacionadas

header() escreve um cabeçalho por vez, mas o PHP possui auxiliares de nível superior para os casos mais comuns:

• setcookie() e setrawcookie() — definem um cabeçalho Set-Cookie sem formatá-lo manualmente. Veja PHP Cookies.
• http_response_code() — lê ou define o código de status.
• PHP Sessions — session_start() em si envia cabeçalhos de cookie, portanto tem o mesmo requisito de "antes da saída".

Para aprofundar na definição e chamada de suas próprias funções, veja PHP Functions.

Conclusão

A função header() é sua linha direta para os cabeçalhos de resposta HTTP em PHP. As regras são simples: construa a string do cabeçalho, chame header() antes de qualquer saída, e use exit após um redirecionamento. Com ela você pode redirecionar usuários, definir tipos de conteúdo, servir downloads, enviar códigos de status e controlar o cache — os blocos de construção de quase toda resposta PHP dinâmica.

Prática