mirror of
https://github.com/sigmasternchen/php-doc-en
synced 2025-03-25 21:38:56 +00:00
158f89672a
git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@343909 c90b9560-bf6c-de11-be94-00142212c4b1
348 lines
10 KiB
XML
348 lines
10 KiB
XML
<?xml version="1.0" encoding="utf-8"?>
|
|
<!-- $Revision$ -->
|
|
<refentry xmlns:xlink="http://www.w3.org/1999/xlink" xmlns="http://docbook.org/ns/docbook" xml:id="function.header">
|
|
<refnamediv>
|
|
<refname>header</refname>
|
|
<refpurpose>Send a raw HTTP header</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>http_response_code</parameter></methodparam>
|
|
</methodsynopsis>
|
|
<para>
|
|
<function>header</function> is used to send a raw <acronym>HTTP</acronym>
|
|
header. See the <link xlink:href="&url.rfc;2616">HTTP/1.1 specification</link>
|
|
for more information on <acronym>HTTP</acronym> headers.
|
|
</para>
|
|
<para>
|
|
Remember that <function>header</function> must be called before any
|
|
actual output is sent, either by normal HTML tags, blank lines in a
|
|
file, or from PHP. It is a very common error to read code with
|
|
<function>include</function>, or <function>require</function>,
|
|
functions, or another file access function, and have spaces or empty
|
|
lines that are output before <function>header</function> is called.
|
|
The same problem exists when using a single PHP/HTML file.
|
|
<informalexample>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<html>
|
|
<?php
|
|
/* This will give an error. Note the output
|
|
* above, which is before the header() call */
|
|
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>
|
|
The header string.
|
|
</para>
|
|
<para>
|
|
There are two special-case header calls. The first is a header
|
|
that starts with the string "<literal>HTTP/</literal>" (case is not
|
|
significant), which will be used to figure out the HTTP status
|
|
code to send. For example, if you have configured Apache to
|
|
use a PHP script to handle requests for missing files (using
|
|
the <literal>ErrorDocument</literal> directive), you may want to
|
|
make sure that your script generates the proper status code.
|
|
</para>
|
|
<para>
|
|
<informalexample>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
header("HTTP/1.0 404 Not Found");
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
</informalexample>
|
|
</para>
|
|
<para>
|
|
The second special case is the "Location:" header. Not only does
|
|
it send this header back to the browser, but it also returns a
|
|
<literal>REDIRECT</literal> (302) status code to the browser
|
|
unless the <literal>201</literal> or
|
|
a <literal>3xx</literal> status code has already been set.
|
|
</para>
|
|
<para>
|
|
<informalexample>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
header("Location: http://www.example.com/"); /* Redirect browser */
|
|
|
|
/* Make sure that code below does not get executed when we redirect. */
|
|
exit;
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
</informalexample>
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><parameter>replace</parameter></term>
|
|
<listitem>
|
|
<para>
|
|
The optional <parameter>replace</parameter> parameter indicates
|
|
whether the header should replace a previous similar header, or
|
|
add a second header of the same type. By default it will replace,
|
|
but if you pass in &false; as the second argument you can force
|
|
multiple headers of the same type. For example:
|
|
</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>http_response_code</parameter></term>
|
|
<listitem>
|
|
<para>
|
|
Forces the HTTP response code to the specified value. Note that this
|
|
parameter only has an effect if the <parameter>header</parameter> is
|
|
not empty.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1 role="returnvalues">
|
|
&reftitle.returnvalues;
|
|
<para>
|
|
&return.void;
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1 role="changelog">
|
|
&reftitle.changelog;
|
|
<para>
|
|
<informaltable>
|
|
<tgroup cols="2">
|
|
<thead>
|
|
<row>
|
|
<entry>&Version;</entry>
|
|
<entry>&Description;</entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row>
|
|
<entry>5.1.2</entry>
|
|
<entry>
|
|
This function now prevents more than one header to be sent at once as
|
|
a protection against header injection attacks.
|
|
</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</informaltable>
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1 role="examples">
|
|
&reftitle.examples;
|
|
<para>
|
|
<example>
|
|
<title>Download dialog</title>
|
|
<para>
|
|
If you want the user to be prompted to save the data you are
|
|
sending, such as a generated PDF file, you can use the <link
|
|
xlink:href="&url.rfc;2183">Content-Disposition</link> header to
|
|
supply a recommended filename and force the browser to display the
|
|
save dialog.
|
|
</para>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
// We'll be outputting a PDF
|
|
header('Content-Type: application/pdf');
|
|
|
|
// It will be called downloaded.pdf
|
|
header('Content-Disposition: attachment; filename="downloaded.pdf"');
|
|
|
|
// The PDF source is in original.pdf
|
|
readfile('original.pdf');
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
</example>
|
|
</para>
|
|
<para>
|
|
<example>
|
|
<title>Caching directives</title>
|
|
<para>
|
|
PHP scripts often generate dynamic content that must not be cached
|
|
by the client browser or any proxy caches between the server and the
|
|
client browser. Many proxies and clients can be forced to disable
|
|
caching with:
|
|
</para>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
header("Cache-Control: no-cache, must-revalidate"); // HTTP/1.1
|
|
header("Expires: Sat, 26 Jul 1997 05:00:00 GMT"); // Date in the past
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
<para>
|
|
<note>
|
|
<para>
|
|
You may find that your pages aren't cached even if you don't
|
|
output all of the headers above. There are a number of options
|
|
that users may be able to set for their browser that change its
|
|
default caching behavior. By sending the headers above, you should
|
|
override any settings that may otherwise cause the output of your
|
|
script to be cached.
|
|
</para>
|
|
<para>
|
|
Additionally, <function>session_cache_limiter</function> and
|
|
the <literal>session.cache_limiter</literal> configuration
|
|
setting can be used to automatically generate the correct
|
|
caching-related headers when sessions are being used.
|
|
</para>
|
|
</note>
|
|
</para>
|
|
</example>
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1 role="notes">
|
|
&reftitle.notes;
|
|
¬e.network.header.sapi;
|
|
<note>
|
|
<para>
|
|
You can use output buffering to get around this problem,
|
|
with the overhead of all of your output to the browser being buffered
|
|
in the server until you send it. You can do this by calling
|
|
<function>ob_start</function> and <function>ob_end_flush</function>
|
|
in your script, or setting the <literal>output_buffering</literal>
|
|
configuration directive on in your &php.ini; or
|
|
server configuration files.
|
|
</para>
|
|
</note>
|
|
<note>
|
|
<para>
|
|
The HTTP status header line will always be the first sent
|
|
to the client, regardless of the actual <function>header</function>
|
|
call being the first or not. The status may be overridden
|
|
by calling <function>header</function> with a new status line
|
|
at any time unless the HTTP headers have already been sent.
|
|
</para>
|
|
</note>
|
|
<note>
|
|
<para>
|
|
There is a bug in Microsoft Internet Explorer 4.01 that prevents
|
|
this from working. There is no workaround. There is also a bug
|
|
in Microsoft Internet Explorer 5.5 that interferes with this,
|
|
which can be resolved by upgrading to Service Pack 2 or later.
|
|
</para>
|
|
</note>
|
|
<note>
|
|
<simpara>
|
|
If <link linkend="ini.safe-mode">safe mode</link> is enabled the
|
|
uid of the script is added to the <literal>realm</literal> part
|
|
of the <literal>WWW-Authenticate</literal> header if you set
|
|
this header (used for HTTP Authentication).
|
|
</simpara>
|
|
</note>
|
|
<note>
|
|
<para>
|
|
Most contemporary clients accept relative <acronym>URI</acronym>s as argument to
|
|
<link xlink:href="&spec.http1.1;#section-7.1.2">Location:</link>,
|
|
but some older clients require an absolute URI
|
|
including the scheme, hostname and absolute path. You can usually use
|
|
<varname>$_SERVER['HTTP_HOST']</varname>,
|
|
<varname>$_SERVER['PHP_SELF']</varname>
|
|
and <function>dirname</function> to make an absolute URI from a
|
|
relative one yourself:
|
|
<informalexample>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
/* Redirect to a different page in the current directory that was requested */
|
|
$host = $_SERVER['HTTP_HOST'];
|
|
$uri = rtrim(dirname($_SERVER['PHP_SELF']), '/\\');
|
|
$extra = 'mypage.php';
|
|
header("Location: http://$host$uri/$extra");
|
|
exit;
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
</informalexample>
|
|
</para>
|
|
</note>
|
|
<note>
|
|
<para>
|
|
Session ID is not passed with Location header even if <link
|
|
linkend="ini.session.use-trans-sid">session.use_trans_sid</link> is
|
|
enabled. It must by passed manually using <constant>SID</constant>
|
|
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>
|
|
The section on <link linkend="features.http-auth">HTTP
|
|
authentication</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
|
|
-->
|