mirror of
https://github.com/sigmasternchen/php-doc-en
synced 2025-03-16 17:08:54 +00:00
bfa3989af5
git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@128234 c90b9560-bf6c-de11-be94-00142212c4b1
418 lines
15 KiB
XML
418 lines
15 KiB
XML
<!-- D O N O T E D I T T H I S F I L E ! ! !
|
|
|
|
it is still here for historical reasons only
|
|
(as translators may need to check old revision diffs)
|
|
|
|
if you want to change things documented in this file
|
|
you should now edit the files found under en/reference
|
|
instead -->
|
|
|
|
<?xml version="1.0" encoding="iso-8859-1"?>
|
|
<!-- $Revision: 1.47 $ -->
|
|
<reference id="ref.http">
|
|
<title>HTTP functions</title>
|
|
<titleabbrev>HTTP</titleabbrev>
|
|
|
|
<partintro>
|
|
<simpara>
|
|
These functions let you manipulate the output sent back to the
|
|
remote browser right down to the HTTP protocol level.
|
|
</simpara>
|
|
</partintro>
|
|
|
|
<refentry id="function.header">
|
|
<refnamediv>
|
|
<refname>header</refname>
|
|
<refpurpose>Send a raw HTTP header</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<methodsynopsis>
|
|
<type>int</type><methodname>header</methodname>
|
|
<methodparam><type>string</type><parameter>string</parameter></methodparam>
|
|
<methodparam choice="opt"><type>bool</type><parameter>replace</parameter></methodparam>
|
|
</methodsynopsis>
|
|
<para>
|
|
<function>header</function> is used to send raw
|
|
<acronym>HTTP</acronym> headers. See the <ulink
|
|
url="&spec.http1.1;">HTTP/1.1 specification</ulink> for more
|
|
information on <acronym>HTTP</acronym> headers.
|
|
</para>
|
|
<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:
|
|
<informalexample>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
header('WWW-Authenticate: Negotiate');
|
|
header('WWW-Authenticate: NTLM',false);
|
|
]]>
|
|
</programlisting>
|
|
</informalexample>
|
|
</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.
|
|
<informalexample>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
header("HTTP/1.0 404 Not Found");
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
</informalexample>
|
|
<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>
|
|
In PHP 3, this only works when PHP is compiled as an Apache
|
|
module. You can achieve the same effect using the
|
|
<literal>Status</literal> header.
|
|
<informalexample>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
header("Status: 404 Not Found");
|
|
]]>
|
|
</programlisting>
|
|
</informalexample>
|
|
</para>
|
|
</note>
|
|
</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
|
|
some <literal>3xx</literal> status code has already been set.
|
|
<informalexample>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
header("Location: http://www.example.com/"); /* Redirect browser */
|
|
exit; /* Make sure that code below does
|
|
not get executed when we redirect. */
|
|
]]>
|
|
</programlisting>
|
|
</informalexample>
|
|
</para>
|
|
<note>
|
|
<para>
|
|
HTTP/1.1 requires an absolute <acronym>URI</acronym> as argument to
|
|
<ulink url="&spec.http1.1;-sec14.html#sec14.30">Location:</ulink>
|
|
including the scheme, hostname and absolute path, but
|
|
some clients accept relative URIs. You can usually use
|
|
<literal>$_SERVER['HTTP_HOST']</literal>, <literal>$_SERVER['PHP_SELF']</literal>
|
|
and <function>dirname</function> to make an absolute URI from a
|
|
relative one yourself:
|
|
<informalexample>
|
|
<programlisting>
|
|
<![CDATA[
|
|
header("Location: http://".$_SERVER['HTTP_HOST']
|
|
.dirname($_SERVER['PHP_SELF'])
|
|
."/".$relative_url);
|
|
]]>
|
|
</programlisting>
|
|
</informalexample>
|
|
</para>
|
|
</note>
|
|
<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
|
|
<informalexample>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
header("Expires: Mon, 26 Jul 1997 05:00:00 GMT"); // Date in the past
|
|
header("Last-Modified: " . gmdate("D, d M Y H:i:s") . " GMT");
|
|
// always modified
|
|
header("Cache-Control: no-store, no-cache, must-revalidate"); // HTTP/1.1
|
|
header("Cache-Control: post-check=0, pre-check=0", false);
|
|
header("Pragma: no-cache"); // HTTP/1.0
|
|
]]>
|
|
</programlisting>
|
|
</informalexample>
|
|
<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>
|
|
<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[
|
|
|
|
<?php header ("Content-type: audio/x-pn-realaudio"); ?>
|
|
// Broken, note the blank line above
|
|
]]>
|
|
</programlisting>
|
|
</informalexample>
|
|
<note>
|
|
<para>
|
|
In PHP 4, 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>
|
|
</para>
|
|
<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 <ulink
|
|
url="&url.rfc;2183">Content-Disposition</ulink> header to
|
|
supply a recommended filename and force the browser to display the
|
|
save dialog.
|
|
<informalexample>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
header("Content-type: application/pdf");
|
|
header("Content-Disposition: attachment; filename=downloaded.pdf");
|
|
|
|
/* ... output pdf file ... */
|
|
]]>
|
|
</programlisting>
|
|
</informalexample>
|
|
<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>
|
|
</para>
|
|
<para>
|
|
See also <function>headers_sent</function>,
|
|
<function>setcookie</function>, and the section on
|
|
<link linkend="features.http-auth">HTTP authentication</link>.
|
|
</para>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="function.headers-sent">
|
|
<refnamediv>
|
|
<refname>headers_sent</refname>
|
|
<refpurpose>Returns &true; if headers have been sent</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<methodsynopsis>
|
|
<type>bool</type><methodname>headers_sent</methodname>
|
|
<void/>
|
|
</methodsynopsis>
|
|
<para>
|
|
This function returns &true; if the HTTP headers have already been
|
|
sent, &false; otherwise.
|
|
</para>
|
|
<para>
|
|
See also <function>header</function>
|
|
</para>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="function.setcookie">
|
|
<refnamediv>
|
|
<refname>setcookie</refname>
|
|
<refpurpose>Send a cookie</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<methodsynopsis>
|
|
<type>int</type><methodname>setcookie</methodname>
|
|
<methodparam><type>string</type><parameter>name</parameter></methodparam>
|
|
<methodparam choice="opt"><type>string</type><parameter>value</parameter></methodparam>
|
|
<methodparam choice="opt"><type>int</type><parameter>expire</parameter></methodparam>
|
|
<methodparam choice="opt"><type>string</type><parameter>path</parameter></methodparam>
|
|
<methodparam choice="opt"><type>string</type><parameter>domain</parameter></methodparam>
|
|
<methodparam choice="opt"><type>int</type><parameter>secure</parameter></methodparam>
|
|
</methodsynopsis>
|
|
<para>
|
|
<function>setcookie</function> defines a cookie to be sent along
|
|
with the rest of the header information. Cookies must be sent
|
|
<emphasis>before</emphasis> any other headers are sent (this is a
|
|
restriction of cookies, not PHP). This requires you to place
|
|
calls to this function before any <literal><html></literal> or
|
|
<literal><head></literal> tags.
|
|
</para>
|
|
<para>
|
|
All the arguments except the <parameter>name</parameter> argument
|
|
are optional. If only the name argument is present, the cookie
|
|
by that name will be deleted from the remote client. You may
|
|
also replace any argument with an empty string
|
|
(<emphasis>""</emphasis>) in order to skip that
|
|
argument. The <parameter>expire</parameter> and
|
|
<parameter>secure</parameter> arguments are integers and cannot
|
|
be skipped with an empty string. Use a zero
|
|
(<emphasis>0</emphasis>) instead. The
|
|
<parameter>expire</parameter> argument is a regular Unix time
|
|
integer as returned by the <function>time</function> or
|
|
<function>mktime</function> functions. The
|
|
<parameter>secure</parameter> indicates that the cookie should
|
|
only be transmitted over a secure HTTPS connection.
|
|
</para>
|
|
<para>
|
|
Common Pitfalls:
|
|
<itemizedlist>
|
|
<listitem>
|
|
<simpara>
|
|
Cookies will not become visible until the next loading of a page that
|
|
the cookie should be visible for.
|
|
</simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara>
|
|
Cookies must be deleted with the same parameters as they were set with.
|
|
</simpara>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
<simpara>
|
|
In PHP 3, multiple calls to <function>setcookie</function> in the same
|
|
script will be performed in reverse order. If you are trying to
|
|
delete one cookie before inserting another you should put the
|
|
insert before the delete. In PHP 4, multiple calls to
|
|
<function>setcookie</function> are performed in the order called.
|
|
</simpara>
|
|
<para>
|
|
Some examples follow how to send cookies:
|
|
<example>
|
|
<title><function>setcookie</function> send examples</title>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
setcookie ("TestCookie", $value);
|
|
setcookie ("TestCookie", $value,time()+3600); /* expire in 1 hour */
|
|
setcookie ("TestCookie", $value,time()+3600, "/~rasmus/", ".utoronto.ca", 1);
|
|
]]>
|
|
</programlisting>
|
|
</example>
|
|
</para>
|
|
<para>
|
|
When deleting a cookie you should assure that the expiration date
|
|
is in the past, to trigger the removal mechanism in your browser.
|
|
Examples follow how to delete cookies sent in previous example:
|
|
<example>
|
|
<title><function>setcookie</function> delete examples</title>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
// set the expiration date to one hour ago
|
|
setcookie ("TestCookie", "", time() - 3600);
|
|
setcookie ("TestCookie", "", time() - 3600, "/~rasmus/", ".utoronto.ca", 1);
|
|
]]>
|
|
</programlisting>
|
|
</example>
|
|
</para>
|
|
<para>
|
|
Note that the value portion of the cookie will automatically be
|
|
urlencoded when you send the cookie, and when it is received, it
|
|
is automatically decoded and assigned to a variable by the same
|
|
name as the cookie name. To see the contents of our test
|
|
cookie in a script, simply use one of the following examples:
|
|
<informalexample>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
echo $TestCookie;
|
|
echo $HTTP_COOKIE_VARS["TestCookie"];
|
|
]]>
|
|
</programlisting>
|
|
</informalexample>
|
|
</para>
|
|
<para>
|
|
You may also set array cookies by using array notation in the
|
|
cookie name. This has the effect of setting as many cookies as
|
|
you have array elements, but when the cookie is received by your
|
|
script, the values are all placed in an array with the cookie's
|
|
name:
|
|
<informalexample>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
setcookie ("cookie[three]", "cookiethree");
|
|
setcookie ("cookie[two]", "cookietwo");
|
|
setcookie ("cookie[one]", "cookieone");
|
|
if (isset ($cookie)) {
|
|
while (list ($name, $value) = each ($cookie)) {
|
|
echo "$name == $value<br>\n";
|
|
}
|
|
}
|
|
]]>
|
|
</programlisting>
|
|
</informalexample>
|
|
</para>
|
|
<para>
|
|
For more information on cookies, see Netscape's cookie
|
|
specification at <ulink
|
|
url="&spec.cookies;">&spec.cookies;</ulink>.
|
|
</para>
|
|
<simpara>
|
|
Microsoft Internet Explorer 4 with Service Pack 1 applied does
|
|
not correctly deal with cookies that have their path parameter
|
|
set.
|
|
</simpara>
|
|
<simpara>
|
|
Netscape Communicator 4.05 and Microsoft Internet Explorer 3.x
|
|
appear to handle cookies incorrectly when the path and time
|
|
are not set.
|
|
</simpara>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
</reference>
|
|
|
|
<!-- 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:"../../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
|
|
-->
|
|
|