mirror of
https://github.com/php/doc-pt_br.git
synced 2026-03-24 07:02:09 +01:00
342 lines
11 KiB
XML
342 lines
11 KiB
XML
<?xml version="1.0" encoding="utf-8"?>
|
|
<!-- EN-Revision: 5c1ccc6e24e5d470e75ef0a5887c2ff583266375 Maintainer: leonardolara Status: ready -->
|
|
<refentry xmlns:xlink="http://www.w3.org/1999/xlink" xmlns="http://docbook.org/ns/docbook" xml:id="function.header">
|
|
<refnamediv>
|
|
<refname>header</refname>
|
|
<refpurpose>Envia um cabeçalho HTTP bruto</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsect1 role="description">
|
|
&reftitle.description;
|
|
<methodsynopsis>
|
|
<type>void</type><methodname>header</methodname>
|
|
<methodparam><type>string</type><parameter>header</parameter></methodparam>
|
|
<methodparam choice="opt"><type>bool</type><parameter>replace</parameter><initializer>&true;</initializer></methodparam>
|
|
<methodparam choice="opt"><type>int</type><parameter>response_code</parameter><initializer>0</initializer></methodparam>
|
|
</methodsynopsis>
|
|
<para>
|
|
<function>header</function> é usada para enviar um cabeçalho <acronym>HTTP</acronym>
|
|
bruto. Consulte a <link xlink:href="&url.rfc;2616">especificação HTTP/1.1</link>
|
|
para obter mais informações sobre cabeçalhos <acronym>HTTP</acronym>.
|
|
</para>
|
|
<para>
|
|
Lembre-se de que <function>header</function> deve ser chamada antes
|
|
de qualquer saída real ser enviada, seja por tags HTML normais, linhas em branco em um
|
|
arquivo ou pelo PHP. É um erro muito comum ler código com
|
|
<function>include</function>, <function>require</function>,
|
|
funções ou outra função de acesso a arquivo, e ter espaços ou linhas
|
|
vazias que são exibidas antes de <function>header</function> ser chamada.
|
|
O mesmo problema existe ao usar um único arquivo PHP/HTML.
|
|
<informalexample>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<html>
|
|
<?php
|
|
/* Isso causará um erro. Observe a saída
|
|
* acima, que é antes da chamada header() */
|
|
header('Location: http://www.example.com/');
|
|
exit;
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
</informalexample>
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1 role="parameters">
|
|
&reftitle.parameters;
|
|
<para>
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><parameter>header</parameter></term>
|
|
<listitem>
|
|
<para>
|
|
A string do cabeçalho.
|
|
</para>
|
|
<para>
|
|
Existem dois casos especiais de chamadas de cabeçalho. O primeiro é um cabeçalho
|
|
que começa com a string "<literal>HTTP/</literal>" (maiúsculas ou minúsculas,
|
|
não importa), que será usado para descobrir o código de status HTTP
|
|
a ser enviado. Por exemplo, se o Apache foi configurado para
|
|
usar um script PHP para lidar com solicitações de arquivos ausentes (usando
|
|
a diretiva <literal>ErrorDocument</literal>), é importante ter
|
|
certeza de que o script gera o código de status adequado.
|
|
</para>
|
|
<para>
|
|
<informalexample>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
// Este exemplo ilustra o caso especial "HTTP/"
|
|
// Alternativas melhores em casos de uso típico incluem:
|
|
// 1. header($_SERVER["SERVER_PROTOCOL"] . " 404 Not Found");
|
|
// (para substituir as mensagens de status HTTP para clientes que ainda estão usando HTTP/1.0)
|
|
// 2. http_response_code(404); (para usar a mensagem padrão)
|
|
header("HTTP/1.1 404 Not Found");
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
</informalexample>
|
|
</para>
|
|
<para>
|
|
O segunda caso especial é o cabeçalho "Location:". Ele não só envia
|
|
o cabeçalho de volta para o navegador, mas também retorna um código de
|
|
status <literal>REDIRECT</literal> (302) para o navegador
|
|
a menos que o código de status <literal>201</literal> ou
|
|
um <literal>3xx</literal> já tenha sido enviado.
|
|
</para>
|
|
<para>
|
|
<informalexample>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
header("Location: http://www.example.com/"); /* Redireciona o navegador */
|
|
|
|
/* Certificando que o restante do código não seja executado quando o redirecionamento é feito. */
|
|
exit;
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
</informalexample>
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><parameter>replace</parameter></term>
|
|
<listitem>
|
|
<para>
|
|
O parâmetro opcional <parameter>replace</parameter> indica
|
|
se o cabeçalho deve substituir um cabeçalho semelhante anterior ou
|
|
adicionar um segundo cabeçalho do mesmo tipo. Por padrão ele irá substituir,
|
|
mas se for passado &false; como segundo argumento podem ser forçados
|
|
vários cabeçalhos do mesmo tipo. Por exemplo:
|
|
</para>
|
|
<para>
|
|
<informalexample>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
header('WWW-Authenticate: Negotiate');
|
|
header('WWW-Authenticate: NTLM', false);
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
</informalexample>
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><parameter>response_code</parameter></term>
|
|
<listitem>
|
|
<para>
|
|
Força o código de resposta HTTP para o valor especificado. Observe que este
|
|
parâmetro só tem efeito se o parâmetro <parameter>header</parameter> não
|
|
estiver vazio.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1 role="returnvalues">
|
|
&reftitle.returnvalues;
|
|
<para>
|
|
&return.void;
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1 role="errors">
|
|
&reftitle.errors;
|
|
<para>
|
|
Em caso de falha ao programar o envio do cabeçalho, <function>header</function>
|
|
emitirá um erro de nível <constant>E_WARNING</constant>.
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1 role="examples">
|
|
&reftitle.examples;
|
|
<para>
|
|
<example>
|
|
<title>Caixa de diálogo para salvar arquivo</title>
|
|
<para>
|
|
Se quiser que o usuário seja solicitado a salvar os dados que estão sendo
|
|
enviados, como um arquivo PDF gerado por exemplo, pode ser usado o cabeçalho <link
|
|
xlink:href="&url.rfc;2183">Content-Disposition</link> para
|
|
fornecer um nome de arquivo recomendado e forçar o navegador a exibir
|
|
a caixa de diálogo para salvá-lo.
|
|
</para>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
// A saída será um PDF
|
|
header('Content-Type: application/pdf');
|
|
|
|
// Será chamado de downloaded.pdf
|
|
header('Content-Disposition: attachment; filename="downloaded.pdf"');
|
|
|
|
// A fonte do PDF está em original.pdf
|
|
readfile('original.pdf');
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
</example>
|
|
</para>
|
|
<para>
|
|
<example>
|
|
<title>Diretivas de cache</title>
|
|
<para>
|
|
Os scripts PHP geralmente geram conteúdo dinâmico que não deve ser armazenado em cache
|
|
pelo navegador do cliente ou por qualquer cache proxy entre o servidor e o
|
|
navegador do cliente. Muitos proxies e clientes podem ser forçados a desabilitar
|
|
o cache com:
|
|
</para>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
header("Cache-Control: no-cache, must-revalidate"); // HTTP/1.1
|
|
header("Expires: Sat, 03 Dec 2016 17:15:00 GMT"); // Data no passado
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
<para>
|
|
<note>
|
|
<para>
|
|
Pode acontecer das páginas não serem armazenadas em cache mesmo que todos os
|
|
cabeçalhos acima não sejam gerados. Há uma série de opções
|
|
que os usuários podem definir para seus navegadores que alteram seu
|
|
comportamento padrão de cache. Ao enviar os cabeçalhos acima, devem ser
|
|
substituídas quaisquer configurações que possam fazer com que a saída do
|
|
script seja armazenada em cache.
|
|
</para>
|
|
<para>
|
|
Além disso, <function>session_cache_limiter</function> e
|
|
a configuração <literal>session.cache_limiter</literal>
|
|
podem ser usadas para gerar automaticamente os cabeçalhos
|
|
corretos relacionados ao cache quando sessões estão sendo usadas.
|
|
</para>
|
|
</note>
|
|
</para>
|
|
</example>
|
|
</para>
|
|
<para>
|
|
<example>
|
|
<title>Definindo um cookie</title>
|
|
<para>
|
|
<function>setcookie</function> fornece uma maneira conveniente de definir cookies.
|
|
Para definir um cookie que inclui atributos que <function>setcookie</function>
|
|
não suporta, <function>header</function> pode ser usada.
|
|
</para>
|
|
<para>
|
|
Por exemplo, o código a seguir define um cookie que inclui um
|
|
atributo <literal>Partitioned</literal>.
|
|
</para>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
header('Set-Cookie: name=value; Secure; Path=/; SameSite=None; Partitioned;');
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
</example>
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1 role="notes">
|
|
&reftitle.notes;
|
|
¬e.network.header.sapi;
|
|
<note>
|
|
<para>
|
|
Para contornar esse problema, o buffer de saída pode ser usado,
|
|
com a sobrecarga de toda a saída para o navegador sendo armazenada em buffer
|
|
no servidor até seja enviada. Isso pode ser feito chamando
|
|
<function>ob_start</function> e <function>ob_end_flush</function>
|
|
no script, ou definindo a diretiva de configuração <literal>output_buffering</literal>
|
|
no arquivo &php.ini; ou nos arquivos
|
|
de configuração do servidor.
|
|
</para>
|
|
</note>
|
|
<note>
|
|
<para>
|
|
A linha do cabeçalho de status HTTP sempre será a primeira enviada
|
|
ao cliente, independentemente de a chamada a <function>header</function>
|
|
ser a primeira ou não. O status pode ser substituído
|
|
chamando <function>header</function> com uma nova linha de status
|
|
a qualquer momento, a menos que os cabeçalhos HTTP já tenham sido enviados.
|
|
</para>
|
|
</note>
|
|
<note>
|
|
<para>
|
|
A maioria dos clientes atuais aceita <acronym>URI</acronym> relativo como argumento para
|
|
<link xlink:href="&spec.http1.1;#section-7.1.2">Local:</link>,
|
|
mas alguns clientes mais antigos exigem um URI absoluto
|
|
incluindo o esquema, nome do host e caminho absoluto. Geralmente, podem ser usados
|
|
<varname>$_SERVER['HTTP_HOST']</varname>,
|
|
<varname>$_SERVER['PHP_SELF']</varname>
|
|
e <function>dirname</function> para criar um URI absoluto a partir de um
|
|
relativo:
|
|
<informalexample>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
/* Redireciona para uma página diferente no diretório atual que foi solicitado */
|
|
$host = $_SERVER['HTTP_HOST'];
|
|
$uri = rtrim(dirname($_SERVER['PHP_SELF']), '/\\');
|
|
$extra = 'minha_pagina.php';
|
|
header("Location: http://$host$uri/$extra");
|
|
exit;
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
</informalexample>
|
|
</para>
|
|
</note>
|
|
<note>
|
|
<para>
|
|
O ID da sessão não é passado com o cabeçalho "Location:" mesmo se <link
|
|
linkend="ini.session.use-trans-sid">session.use_trans_sid</link> estiver
|
|
ativada. Deve ser passado manualmente usando a
|
|
constante <constant>SID</constant>.
|
|
</para>
|
|
</note>
|
|
</refsect1>
|
|
|
|
<refsect1 role="seealso">
|
|
&reftitle.seealso;
|
|
<para>
|
|
<simplelist>
|
|
<member><function>headers_sent</function></member>
|
|
<member><function>setcookie</function></member>
|
|
<member><function>http_response_code</function></member>
|
|
<member><function>header_remove</function></member>
|
|
<member><function>headers_list</function></member>
|
|
<member>
|
|
A seção sobre <link linkend="features.http-auth">autenticação
|
|
HTTP</link>
|
|
</member>
|
|
</simplelist>
|
|
</para>
|
|
</refsect1>
|
|
|
|
</refentry>
|
|
<!-- Keep this comment at the end of the file
|
|
Local variables:
|
|
mode: sgml
|
|
sgml-omittag:t
|
|
sgml-shorttag:t
|
|
sgml-minimize-attributes:nil
|
|
sgml-always-quote-attributes:t
|
|
sgml-indent-step:1
|
|
sgml-indent-data:t
|
|
indent-tabs-mode:nil
|
|
sgml-parent-document:nil
|
|
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
|
|
sgml-exposed-tags:nil
|
|
sgml-local-catalogs:nil
|
|
sgml-local-ecat-files:nil
|
|
End:
|
|
vim600: syn=xml fen fdm=syntax fdl=2 si
|
|
vim: et tw=78 syn=sgml
|
|
vi: ts=1 sw=1
|
|
-->
|