1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
|
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision: 330342 $ -->
<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>string</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>string</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>string</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>4.4.2 and 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>
<row>
<entry>4.3.0</entry>
<entry>
The <parameter>http_response_code</parameter> parameter was added.
</entry>
</row>
<row>
<entry>4.0.4</entry>
<entry>
The <parameter>replace</parameter> parameter was added.
</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>
HTTP/1.1 requires an absolute <acronym>URI</acronym> as argument to
<link xlink:href="&spec.http1.1;-sec14.html#sec14.30">Location:</link>
including the scheme, hostname and absolute path, but
some clients accept relative URIs. 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>
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
-->
|
