reference/outcontrol/functions/ob-start.xml
d715365c098db000eaf7dcd987ee6093f6e83091
...
...
@@ -10,42 +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>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.
28
-
</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
-
<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
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
44
29
through each of them in nesting order.
30
+
See <xref linkend="outcontrol.nesting-output-buffers"/> for more details.
45
31
</para>
46
32
<para>
47
-
If outbut buffering is still active when the script ends, PHP outputs the
48
-
contents automatically.
33
+
See <xref linkend="outcontrol.user-level-output-buffers"/>
34
+
for a detailed description of output buffers.
49
35
</para>
50
36
</refsect1>
51
37

...
...
@@ -57,19 +43,16 @@
57
43
<term><parameter>callback</parameter></term>
58
44
<listitem>
59
45
<para>
60
-
An optional <parameter>callback</parameter> function may be
61
-
specified. This function takes a string as a parameter and should
62
-
return a string. The function will be called when
63
-
the output buffer is flushed (sent) or cleaned (with
64
-
<function>ob_flush</function>, <function>ob_clean</function> or similar
65
-
function) or when the output buffer
66
-
is flushed to the browser at the end of the request. When
67
-
<parameter>callback</parameter> is called, it will receive the
68
-
contents of the output buffer as its parameter and is expected to
69
-
return a new output buffer as a result, which will be sent to the
70
-
browser. If the <parameter>callback</parameter> is not a
71
-
callable function, this function will return &false;.
72
-
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:
73
56
</para>
74
57
<para>
75
58
<methodsynopsis>
...
...
@@ -90,52 +73,52 @@
90
73
<term><parameter>phase</parameter></term>
91
74
<listitem>
92
75
<simpara>
93
-
Bitmask of <link linkend="outcontrol.constants"><constant>PHP_OUTPUT_HANDLER_*</constant> constants</link>.
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.
94
83
</simpara>
95
84
</listitem>
96
85
</varlistentry>
97
86
</variablelist>
98
87
</para>
99
88
<para>
100
-
If <parameter>callback</parameter> returns &false; original
101
-
input is sent to the browser.
102
-
</para>
103
-
<para>
104
-
The <parameter>callback</parameter> parameter may be bypassed
105
-
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.
106
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>
107
104
<para>
108
-
<function>ob_end_clean</function>, <function>ob_end_flush</function>,
109
-
<function>ob_clean</function>, <function>ob_flush</function> and
110
-
<function>ob_start</function> may not be called from a callback
111
-
function. If you call them from callback function, the behavior is
112
-
undefined. If you would like to delete the contents of a buffer,
113
-
return "" (a null string) from callback function.
114
-
You can't even call functions using the output buffering functions like
115
-
<literal>print_r($expression, true)</literal> or
116
-
<literal>highlight_file($filename, true)</literal> from a callback
117
-
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).
118
108
</para>
119
-
<note>
120
-
<para>
121
-
<function>ob_gzhandler</function> function exists to
122
-
facilitate sending gz-encoded data to web browsers that support
123
-
compressed web pages. <function>ob_gzhandler</function> determines
124
-
what type of content encoding the browser will accept and will return
125
-
its output accordingly.
126
-
</para>
127
-
</note>
128
109
</listitem>
129
110
</varlistentry>
130
111
<varlistentry>
131
112
<term><parameter>chunk_size</parameter></term>
132
113
<listitem>
133
114
<para>
134
-
If the optional parameter <parameter>chunk_size</parameter> is passed, the
135
-
buffer will be flushed after any output call which causes the buffer's
136
-
length to equal or exceed <parameter>chunk_size</parameter>. The default
137
-
value <literal>0</literal> means that the output function will only be
138
-
called when the output buffer is closed.
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>
191
172



Tools (Turkish Manual)