reference/outcontrol/functions/ob-start.xml
d715365c098db000eaf7dcd987ee6093f6e83091
...
...
@@ -1,6 +1,6 @@
1
1
<?xml version="1.0" encoding="utf-8"?>
2
2
<!-- $Revision$ -->
3
-
<refentry xmlns="http://docbook.org/ns/docbook" xml:id="function.ob-start">
3
+
<refentry xml:id="function.ob-start" xmlns="http://docbook.org/ns/docbook">
4
4
<refnamediv>
5
5
<refname>ob_start</refname>
6
6
<refpurpose>Turn on output buffering</refpurpose>
...
...
@@ -10,38 +10,28 @@
10
10
&reftitle.description;
11
11
<methodsynopsis>
12
12
<type>bool</type><methodname>ob_start</methodname>
13
-
<methodparam choice="opt"><type>callable</type><parameter>output_callback</parameter><initializer>&null;</initializer></methodparam>
13
+
<methodparam choice="opt"><type class="union"><type>callable</type><type>null</type></type><parameter>callback</parameter><initializer>&null;</initializer></methodparam>
14
14
<methodparam choice="opt"><type>int</type><parameter>chunk_size</parameter><initializer>0</initializer></methodparam>
15
15
<methodparam choice="opt"><type>int</type><parameter>flags</parameter><initializer><constant>PHP_OUTPUT_HANDLER_STDFLAGS</constant></initializer></methodparam>
16
16
</methodsynopsis>
17
17
<para>
18
-
This function will turn output buffering on. While output buffering is
19
-
active no output is sent from the script (other than headers), instead the
20
-
output is stored in an internal buffer.
18
+
This function will turn output buffering on.
19
+
While output buffering is active no output is sent from the script,
20
+
instead the output is stored in an internal buffer.
21
+
See <xref linkend="outcontrol.what-output-is-buffered"/>
22
+
on exactly what output is affected.
21
23
</para>
22
24
<para>
23
-
The contents of this internal buffer may be copied into a string variable
24
-
using <function>ob_get_contents</function>. To output what is stored in
25
-
the internal buffer, use <function>ob_end_flush</function>. Alternatively,
26
-
<function>ob_end_clean</function> will silently discard the buffer
27
-
contents.
25
+
Output buffers are stackable, that is,
26
+
<function>ob_start</function> may be called while another buffer is active.
27
+
If multiple output buffers are active,
28
+
output is being filtered sequentially
29
+
through each of them in nesting order.
30
+
See <xref linkend="outcontrol.nesting-output-buffers"/> for more details.
28
31
</para>
29
-
<warning>
30
-
<para>
31
-
Some web servers (e.g. Apache) change the working directory of a script
32
-
when calling the callback function. You can change it back by e.g.
33
-
<literal>chdir(dirname($_SERVER['SCRIPT_FILENAME']))</literal> in the
34
-
callback function.
35
-
</para>
36
-
</warning>
37
32
<para>
38
-
Output buffers are stackable, that is, you may call
39
-
<function>ob_start</function> while another
40
-
<function>ob_start</function> is active. Just make
41
-
sure that you call <function>ob_end_flush</function>
42
-
the appropriate number of times. If multiple output callback
43
-
functions are active, output is being filtered sequentially
44
-
through each of them in nesting order.
33
+
See <xref linkend="outcontrol.user-level-output-buffers"/>
34
+
for a detailed description of output buffers.
45
35
</para>
46
36
</refsect1>
47
37

...
...
@@ -50,22 +40,19 @@
50
40
<para>
51
41
<variablelist>
52
42
<varlistentry>
53
-
<term><parameter>output_callback</parameter></term>
43
+
<term><parameter>callback</parameter></term>
54
44
<listitem>
55
45
<para>
56
-
An optional <parameter>output_callback</parameter> function may be
57
-
specified. This function takes a string as a parameter and should
58
-
return a string. The function will be called when
59
-
the output buffer is flushed (sent) or cleaned (with
60
-
<function>ob_flush</function>, <function>ob_clean</function> or similar
61
-
function) or when the output buffer
62
-
is flushed to the browser at the end of the request. When
63
-
<parameter>output_callback</parameter> is called, it will receive the
64
-
contents of the output buffer as its parameter and is expected to
65
-
return a new output buffer as a result, which will be sent to the
66
-
browser. If the <parameter>output_callback</parameter> is not a
67
-
callable function, this function will return &false;.
68
-
This is the callback signature:
46
+
An optional <parameter>callback</parameter> <type>callable</type> may be
47
+
specified. It can also be bypassed by passing &null;.
48
+
</para>
49
+
<para>
50
+
<parameter>callback</parameter> is invoked when the output buffer is
51
+
flushed (sent), cleaned, or when the output buffer is flushed
52
+
at the end of the script.
53
+
</para>
54
+
<para>
55
+
The signature of the <parameter>callback</parameter> is as follows:
69
56
</para>
70
57
<para>
71
58
<methodsynopsis>
...
...
@@ -86,56 +73,52 @@
86
73
<term><parameter>phase</parameter></term>
87
74
<listitem>
88
75
<simpara>
89
-
Bitmask of <constant>PHP_OUTPUT_HANDLER_*</constant> constants.
76
+
Bitmask of
77
+
<link linkend="constant.php-output-handler-start">
78
+
<constant>PHP_OUTPUT_HANDLER_<replaceable>*</replaceable></constant>
79
+
constants
80
+
</link>.
81
+
See <xref linkend="outcontrol.flags-passed-to-output-handlers"/>
82
+
for more details.
90
83
</simpara>
91
84
</listitem>
92
85
</varlistentry>
93
86
</variablelist>
94
87
</para>
95
88
<para>
96
-
If <parameter>output_callback</parameter> returns &false; original
97
-
input is sent to the browser.
98
-
</para>
99
-
<para>
100
-
The <parameter>output_callback</parameter> parameter may be bypassed
101
-
by passing a &null; value.
89
+
If <parameter>callback</parameter> returns &false;
90
+
the contents of the buffer are returned.
91
+
See <xref linkend="outcontrol.output-handler-return-values"/>
92
+
for more details.
102
93
</para>
94
+
<warning>
95
+
<simpara>
96
+
Calling any of the following functions from within an output handler
97
+
will result in a fatal error:
98
+
<function>ob_clean</function>, <function>ob_end_clean</function>,
99
+
<function>ob_end_flush</function>, <function>ob_flush</function>,
100
+
<function>ob_get_clean</function>, <function>ob_get_flush</function>,
101
+
<function>ob_start</function>.
102
+
</simpara>
103
+
</warning>
103
104
<para>
104
-
<function>ob_end_clean</function>, <function>ob_end_flush</function>,
105
-
<function>ob_clean</function>, <function>ob_flush</function> and
106
-
<function>ob_start</function> may not be called from a callback
107
-
function. If you call them from callback function, the behavior is
108
-
undefined. If you would like to delete the contents of a buffer,
109
-
return "" (a null string) from callback function.
110
-
You can't even call functions using the output buffering functions like
111
-
<literal>print_r($expression, true)</literal> or
112
-
<literal>highlight_file($filename, true)</literal> from a callback
113
-
function.
105
+
See <xref linkend="outcontrol.output-handlers"/>
106
+
and <xref linkend="outcontrol.working-with-output-handlers"/>
107
+
for more details on <parameter>callback</parameter>s (output handlers).
114
108
</para>
115
-
<note>
116
-
<para>
117
-
<function>ob_gzhandler</function> function exists to
118
-
facilitate sending gz-encoded data to web browsers that support
119
-
compressed web pages. <function>ob_gzhandler</function> determines
120
-
what type of content encoding the browser will accept and will return
121
-
its output accordingly.
122
-
</para>
123
-
</note>
124
109
</listitem>
125
110
</varlistentry>
126
111
<varlistentry>
127
112
<term><parameter>chunk_size</parameter></term>
128
113
<listitem>
129
114
<para>
130
-
If the optional parameter <parameter>chunk_size</parameter> is passed, the
131
-
buffer will be flushed after any output call which causes the buffer's
132
-
length to equal or exceed <parameter>chunk_size</parameter>. The default
133
-
value <literal>0</literal> means that the output function will only be
134
-
called when the output buffer is closed.
135
-
</para>
136
-
<para>
137
-
Prior to PHP 5.4.0, the value <literal>1</literal> was a special case
138
-
value that set the chunk size to 4096 bytes.
115
+
If the optional parameter <parameter>chunk_size</parameter> is passed,
116
+
the buffer will be flushed after any block of code resulting in output
117
+
that causes the buffer's length to equal
118
+
or exceed <parameter>chunk_size</parameter>.
119
+
The default value <literal>0</literal> means
120
+
that all output is buffered until the buffer is turned off.
121
+
See <xref linkend="outcontrol.buffer-size"/> for more details.
139
122
</para>
140
123
</listitem>
141
124
</varlistentry>
...
...
@@ -146,11 +129,12 @@
146
129
The <parameter>flags</parameter> parameter is a bitmask that controls
147
130
the operations that can be performed on the output buffer. The default
148
131
is to allow output buffers to be cleaned, flushed and removed, which
149
-
can be set explicitly via
150
-
<constant>PHP_OUTPUT_HANDLER_CLEANABLE</constant> |
151
-
<constant>PHP_OUTPUT_HANDLER_FLUSHABLE</constant> |
152
-
<constant>PHP_OUTPUT_HANDLER_REMOVABLE</constant>, or
153
-
<constant>PHP_OUTPUT_HANDLER_STDFLAGS</constant> as shorthand.
132
+
can be set explicitly via the
133
+
<link linkend="outcontrol.constants.buffer-control-flags">
134
+
buffer control flags
135
+
</link>.
136
+
See <xref linkend="outcontrol.operations-on-buffers"/>
137
+
for more details.
154
138
</para>
155
139
<para>
156
140
Each flag controls access to a set of functions, as described below:
...
...
@@ -166,25 +150,22 @@
166
150
<row>
167
151
<entry><constant>PHP_OUTPUT_HANDLER_CLEANABLE</constant></entry>
168
152
<entry>
169
-
<function>ob_clean</function>,
170
-
<function>ob_end_clean</function>, and
171
-
<function>ob_get_clean</function>.
153
+
<function>ob_clean</function>
172
154
</entry>
173
155
</row>
174
156
<row>
175
157
<entry><constant>PHP_OUTPUT_HANDLER_FLUSHABLE</constant></entry>
176
158
<entry>
177
-
<function>ob_end_flush</function>,
178
-
<function>ob_flush</function>, and
179
-
<function>ob_get_flush</function>.
159
+
<function>ob_end_flush</function>
180
160
</entry>
181
161
</row>
182
162
<row>
183
163
<entry><constant>PHP_OUTPUT_HANDLER_REMOVABLE</constant></entry>
184
164
<entry>
185
165
<function>ob_end_clean</function>,
186
-
<function>ob_end_flush</function>, and
187
-
<function>ob_get_flush</function>.
166
+
<function>ob_end_flush</function>,
167
+
<function>ob_get_clean</function>,
168
+
<function>ob_get_flush</function>
188
169
</entry>
189
170
</row>
190
171
</tbody>
...
...
@@ -204,62 +185,6 @@
204
185
</para>
205
186
</refsect1>
206
187

207
-
<refsect1 role="changelog">
208
-
&reftitle.changelog;
209
-
<para>
210
-
<informaltable>
211
-
<tgroup cols="2">
212
-
<thead>
213
-
<row>
214
-
<entry>&Version;</entry>
215
-
<entry>&Description;</entry>
216
-
</row>
217
-
</thead>
218
-
<tbody>
219
-
<row>
220
-
<entry>7.0.0</entry>
221
-
<entry>
222
-
In case <function>ob_start</function> is used inside an output buffer
223
-
callback, this function will no longer issue an <constant>E_ERROR</constant>
224
-
but instead an <constant>E_RECOVERABLE_ERROR</constant>, allowing custom
225
-
error handlers to catch such errors.
226
-
</entry>
227
-
</row>
228
-
<row>
229
-
<entry>5.4.0</entry>
230
-
<entry>
231
-
The third parameter of <function>ob_start</function> changed from a
232
-
<type>boolean</type> parameter called <parameter>erase</parameter>
233
-
(which, if set to &false;, would prevent the output buffer from being
234
-
deleted until the script finished executing) to an
235
-
<type>integer</type> parameter called <parameter>flags</parameter>.
236
-
Unfortunately, this results in an API compatibility break for code
237
-
written prior to PHP 5.4.0 that uses the third parameter. See
238
-
<link linkend="function.ob-start.flags-bc">the flags example</link>
239
-
for an example of how to handle this with code that needs to be
240
-
compatible with both.
241
-
</entry>
242
-
</row>
243
-
<row>
244
-
<entry>5.4.0</entry>
245
-
<entry>
246
-
A chunk size of <literal>1</literal> now results in chunks of 1 byte
247
-
being sent to the output buffer.
248
-
</entry>
249
-
</row>
250
-
<row>
251
-
<entry>4.3.2</entry>
252
-
<entry>
253
-
This function was changed to return &false; in case the passed
254
-
<parameter>output_callback</parameter> can not be executed.
255
-
</entry>
256
-
</row>
257
-
</tbody>
258
-
</tgroup>
259
-
</informaltable>
260
-
</para>
261
-
</refsect1>
262
-

263
188
<refsect1 role="examples">
264
189
&reftitle.examples;
265
190
<para>
...
...
@@ -305,17 +230,12 @@ ob_end_flush();
305
230

306
231
<para>
307
232
<example xml:id="function.ob-start.flags-bc">
308
-
<title>Creating an uneraseable output buffer in a way compatible with both PHP 5.3 and 5.4</title>
233
+
<title>Creating an unerasable output buffer</title>
309
234
<programlisting role="php">
310
235
<![CDATA[
311
236
<?php
312
237

313
-
if (version_compare(PHP_VERSION, '5.4.0', '>=')) {
314
-
ob_start(null, 0, PHP_OUTPUT_HANDLER_STDFLAGS ^
315
-
PHP_OUTPUT_HANDLER_REMOVABLE);
316
-
} else {
317
-
ob_start(null, 0, false);
318
-
}
238
+
ob_start(null, 0, PHP_OUTPUT_HANDLER_STDFLAGS ^ PHP_OUTPUT_HANDLER_REMOVABLE);
319
239

320
240
?>
321
241
]]>
...
...
@@ -341,7 +261,6 @@ if (version_compare(PHP_VERSION, '5.4.0', '>=')) {
341
261
</refsect1>
342
262

343
263
</refentry>
344
-

345
264
<!-- Keep this comment at the end of the file
346
265
Local variables:
347
266
mode: sgml
348
267



Tools (Brazilian Portuguese Manual)