header

(PHP 3, PHP 4 , PHP 5)

header -- Envia um cabeçalho HTTP diretamente

Descrição

void header ( string string [, bool replace [, int http_response_code]] )

header() é usado para enviar diretamete cabeçalhos HTTP headers. Veja a especificação HTTP/1.1 para maiores informações sobre cabeçalhos HTTP.

O parâmetro opcional replace indica quando um cabeçalho deverá substituir um cabeçalho similar anterior, ou adicionar um segundo cabeçalho do mesmo tipo. Por padrão irá substituir, mas se você passar FALSE como segundo argumento você poderá forçar multiplos cabeçalhos do mesmo tipo. Por exemplo:

<?php
header
('WWW-Authenticate: Negotiate');
header('WWW-Authenticate: NTLM', false);
?>

O segundo parâmetro opcional http_response_code força o código de resposta HTTP para o valor especificado. (Este parâmetro esta disonível no PHP 4.3.0 e posterior.)

Existem dois casos especiais de chamadas de cabeçalhos. O primeiro é um cabeçalho que começa com a string "HTTP/" (não é importante se maiúscula ou minúscula), o que será usada para enviar um código de situação HTTP. Por exemplo, se você configurou o apache para usar um script PHP para gerenciar requisições para arquivos que não existam (usando a diretiva ErrorDocument), você deve querer ter certeza que seu script gere o código de situação apropriado.

<?php
header
("HTTP/1.0 404 Not Found");
?>

Nota: A linha com o a situação HTTP será sempre a primeira a ser enviada para o cliente, não importando se o header() foi o primeiro a ser chamado ou não. A situação pode ser sobrescrita utilizando-se header() com uma nova linha de situação a qualquer tempo, a menos que os cabeçalhos HTTP já tenham sido enviados.

Nota: No PHP 3, isto somente funciona quando o PHP é compilado como um módulo do apache. Você poderá ter o mesmo efeito usando o cabeçalho Status.

<?php
header
("Status: 404 Not Found");
?>

O segundo caso especial é o cabeçalho "Location:". Não somente envia o seu cabeçalho para o browser, mas também retorna código de situação REDIRECT (302) para o browser a menos que algum código de situação 3xx já tenha sido definido.

<?php
header
("Location: http://www.example.com/"); /* Redirect browser */

/* Tenha certeza que o código abaixo não seja executado qunado nós redirecionamos. */
exit;
?>

Nota: HTTP/1.1 requer um URI absoluto como argumento para Location: incluindo o tema, nome do servidor e caminho absoluto, mas alguns clientes aceitam URIs relativas. Você normalmente pode usar $_SERVER['HTTP_HOST'], $_SERVER['PHP_SELF'] e dirname() para fazer uma URI absoluta a partir de uma relativapor si mesmo:

<?php
header
("Location: http://" . $_SERVER['HTTP_HOST']
                      .
dirname($_SERVER['PHP_SELF'])
                      .
"/" . $relative_url);
?>

Scripts PHP normalmente geram conteúdo dinamico que não deva ser guardado em cache pelo browser do cliente ou qualquer cache de proxy entre o servidor e o browser do cliente. Muitos proxies e clientes são forçados a desabilitar o cache usando:

<?php
// Data no passado
header("Expires: Mon, 26 Jul 1997 05:00:00 GMT");

// Sempre modificado
header("Last-Modified: " . gmdate("D, d M Y H:i:s") . " GMT");

// HTTP/1.1
header("Cache-Control: no-store, no-cache, must-revalidate");
header("Cache-Control: post-check=0, pre-check=0", false);

// HTTP/1.0
header("Pragma: no-cache");
?>

Nota: Você pode pensar que suas páginas não são colocadas em cache mesmo que você não envie todos os cabeçalhos acima. Existem várias opções que os usuários podem definir em seus browser que mudam o funcionamento do cache. Enviando os cabeçalhos acima, você irá sobrescrever qualquer definição que faça seu script ser colocado em cache.

Adicionalmente as configurações, session_cache_limiter() e session.cache_limiter podem ser usadas para gerar automaticamente os cabeçalhos corretos quando estão sendo usadas sessões.

Lembre-se que header() deve ser utilizada antes que qualquer saida seja enviada, seja pelo HTML, linhas ou espaços em branco em um arquivo, ou a partit do PHP. É um erro muito comum ler código com a função include(), ou require(), ou outra função que acesse arquivos, e ter espaços ou linhas em branco antes da função header(). O mesmo problema existe quando usar um arquivo PHP/HTML.

<html>
<?php
/* Isto irá causar um erro. Note a saída
* acima, o que acontece antes de header() */
header('Location: http://www.example.com/');
?>

Nota: A partir do PHP 4, você pode usar o buffer de saída para contornar este problema, com a sobrecarga que toda a saída do browser será guardada em buffer no servidor até que voc^envie ele. Você poderá fazer isso usando ob_start() e ob_end_flush() no seu script ou definido a diretiva de configuração output_buffering no seu php.ini ou nos arquivos de configuração do servidor.

Se você queira que seja perguntado ao usuário para salvar os dados que você esta enviando, como um arquivo PDF gerado, você pode usar o cabeçalho Content-Disposition para recomendar um nome de arquivo e forçar o browser a mostrar uma caixa salvar arquivo.

<?php
// Nós estaremos enviando um PDF
header('Content-type: application/pdf');

// Será chamado downloaded.pdf
header('Content-Disposition: attachment; filename="downloaded.pdf"');

// A fonte do PDF é original.pdf
readfile('original.pdf');
?>

Nota: Existe um bug no Microsoft Internet Explorer 4.01 que previne que isto acontece. Não existe como contornar. Também existe um bug no Microsoft Internet Explorer 5.5 que interfere com isto, o qual pode ser resolvido atualizando para o Service Pack 2 oo posterior.

Nota: Se safe mode esta ativado o uid do script é adicionado na parte realm do cabeçalho WWW-Authenticate se você definir este cabaçalho (usado para autenticação HTTP).

Veja também headers_sent(), setcookie(), e a seção sobre autenticação HTTP.