diff --git a/reference/outcontrol/functions/flush.xml b/reference/outcontrol/functions/flush.xml index 230b93742a..e5cebdc8e2 100644 --- a/reference/outcontrol/functions/flush.xml +++ b/reference/outcontrol/functions/flush.xml @@ -1,45 +1,43 @@ - - + flush Flush the output buffer - - Description + + + &reftitle.description; voidflush - - Flushes the output buffers of PHP and whatever backend PHP is - using (CGI, a web server, etc). This effectively tries to push - all the output so far to the user's browser. - - flush has no effect on the buffering - scheme of your web server or the browser on the client - side. + Flushes the output buffers of PHP and whatever backend PHP is using (CGI, + a web server, etc). This effectively tries to push all the output so far + to the user's browser. + + + flush has no effect on the buffering scheme of your + web server or the browser on the client side. Thus you need to call both ob_flush and flush to flush the output buffers. - Several servers, especially on Win32, will still buffer - the output from your script until it terminates before - transmitting the results to the browser. + Several servers, especially on Win32, will still buffer the output from + your script until it terminates before transmitting the results to the + browser. - Server modules for Apache like mod_gzip may do buffering of their own - that will cause flush to not result in data being - sent immediately to the client. + Server modules for Apache like mod_gzip may do buffering of their own that + will cause flush to not result in data being sent + immediately to the client. - Even the browser may buffer its input before displaying it. - Netscape, for example, buffers text until it receives an - end-of-line or the beginning of a tag, and it won't render - tables until the </table> tag of the outermost table is - seen. + Even the browser may buffer its input before displaying it. Netscape, for + example, buffers text until it receives an end-of-line or the beginning of + a tag, and it won't render tables until the </table> tag of the + outermost table is seen. Some versions of Microsoft Internet Explorer will only start to display @@ -48,6 +46,14 @@ page. + + + &reftitle.returnvalues; + + &return.void; + + + - + ob_clean Clean (erase) the output buffer - - Description + + + &reftitle.description; voidob_clean @@ -19,12 +19,26 @@ This function does not destroy the output buffer like ob_end_clean does. + + + + &reftitle.returnvalues; - See also ob_flush, - ob_end_flush and - ob_end_clean. + &return.void; + + + &reftitle.seealso; + + + ob_flush + ob_end_flush + ob_end_clean + + + + - + ob_end_clean Clean (erase) the output buffer and turn off output buffering - - Description + + + &reftitle.description; boolob_end_clean - This function discards the contents of the topmost output buffer and - turns off this output buffering. If you want to further - process the buffer's contents you have to call - ob_get_contents before - ob_end_clean as the buffer contents are - discarded when ob_end_clean is called. - The function returns &true; when it successfully - discarded one buffer and &false; otherwise. Reasons for failure are first - that you called the function without an active buffer or that for some - reason a buffer could not be deleted (possible for special buffer). + This function discards the contents of the topmost output buffer and turns + off this output buffering. If you want to further process the buffer's + contents you have to call ob_get_contents before + ob_end_clean as the buffer contents are discarded + when ob_end_clean is called. + + + + &reftitle.returnvalues; + + &return.success; Reasons for failure are first that you called the + function without an active buffer or that for some reason a buffer could + not be deleted (possible for special buffer). + + + + + &reftitle.errors; + + If the function fails it generates an E_NOTICE. + + + + + &reftitle.changelog; + + + + + + &Version; + &Description; + + + + + 4.2.0 + + The boolean return value was added. + + + + + + + + + + &reftitle.examples; The following example shows an easy way to get rid of all output buffers: @@ -41,20 +80,19 @@ ob_end_clean(); - - - If the function fails it generates an E_NOTICE. - - - The boolean return value was added in PHP 4.2.0. - - - - See also ob_start, - ob_get_contents, and - ob_flush. - + + + &reftitle.seealso; + + + ob_start + ob_get_contents + ob_flush + + + + - + ob_end_flush Flush (send) the output buffer and turn off output buffering - - Description + + + &reftitle.description; boolob_end_flush @@ -19,10 +19,6 @@ ob_get_contents before ob_end_flush as the buffer contents are discarded after ob_end_flush is called. - The function returns &true; when it successfully - discarded one buffer and &false; otherwise. Reasons for failure are first - that you called the function without an active buffer or that for some - reason a buffer could not be deleted (possible for special buffer). @@ -30,13 +26,57 @@ that ob_get_flush returns the buffer as a string. + + + + &reftitle.returnvalues; - The following example shows an easy way to flush and end all output - buffers: + &return.success; Reasons for failure are first that you called the + function without an active buffer or that for some reason a buffer could + not be deleted (possible for special buffer). + + + + &reftitle.errors; + + If the function fails it generates an E_NOTICE. + + + + + &reftitle.changelog; + + + + + + &Version; + &Description; + + + + + 4.2.0 + + The boolean return value was added. + + + + + + + + + + &reftitle.examples; <function>ob_end_flush</function> example + + The following example shows an easy way to flush and end all output + buffers: + - - - If the function fails it generates an E_NOTICE. - - - The boolean return value was added in PHP 4.2.0. - - - - See also ob_start, - ob_get_contents, - ob_get_flush, - ob_flush and - ob_end_clean. - + + + &reftitle.seealso; + + + ob_start + ob_get_contents + ob_get_flush + ob_flush + ob_end_clean + + + + - + ob_flush Flush (send) the output buffer - - Description + + + &reftitle.description; voidob_flush - This function will send the contents of the output buffer (if - any). If you want to further - process the buffer's contents you have to call - ob_get_contents before - ob_flush as the buffer contents are - discarded after ob_flush is called. + This function will send the contents of the output buffer (if any). If you + want to further process the buffer's contents you have to call + ob_get_contents before ob_flush + as the buffer contents are discarded after ob_flush + is called. This function does not destroy the output buffer like ob_end_flush does. + + + + &reftitle.returnvalues; - See also ob_get_contents, - ob_clean, - ob_end_flush and - ob_end_clean. + &return.void; + + + &reftitle.seealso; + + + ob_get_contents + ob_clean + ob_end_flush + ob_end_clean + + + + + ob_get_clean Get current buffer contents and delete current output buffer - - Description + + + &reftitle.description; stringob_get_clean - This will return the contents of the output buffer and end output - buffering. If output buffering isn't active then &false; is returned. + Gets the current buffer contents and delete current output buffer. + + ob_get_clean essentially executes both ob_get_contents and ob_end_clean. + + + + &reftitle.returnvalues; + + Returns the contents of the output buffer and end output buffering. + If output buffering isn't active then &false; is returned. + + + + + &reftitle.examples; A simple <function>ob_get_clean</function> example @@ -36,9 +50,7 @@ var_dump($out); ?> ]]> - - Our example will output: - + &example.outputs; - - See also ob_start and - ob_get_contents. - + + + &reftitle.seealso; + + + ob_get_contents + ob_start + + + + - + ob_get_contents Return the contents of the output buffer - - Description + + + &reftitle.description; stringob_get_contents - This will return the contents of the output buffer without clearing it - or &false;, if output buffering isn't active. + Gets the contents of the output buffer without clearing it. + + + + &reftitle.returnvalues; + + This will return the contents of the output buffer or &false;, if output + buffering isn't active. + + + + + &reftitle.examples; A simple <function>ob_get_contents</function> example @@ -39,24 +50,27 @@ var_dump($out1, $out2); ?> ]]> - - Our example will output: - + &example.outputs; - - See also ob_start and - ob_get_length. - + + + &reftitle.seealso; + + + ob_start + ob_get_length + + + + + ob_get_flush Flush the output buffer, return it as a string and turn off output buffering - - Description + + + &reftitle.description; stringob_get_flush @@ -14,8 +15,6 @@ ob_get_flush flushes the output buffer, return it as a string and turns off output buffering. - ob_get_flush returns &false; if no buffering is - active. @@ -23,6 +22,17 @@ that this function returns the buffer as a string. + + + + &reftitle.returnvalues; + + Returns the output buffer or &false; if no buffering is active. + + + + + &reftitle.examples; <function>ob_get_flush</function> example @@ -54,12 +64,19 @@ Array - - See also ob_end_clean, - ob_end_flush and - ob_list_handlers. - + + + &reftitle.seealso; + + + ob_end_clean + ob_end_flush + ob_list_handlers + + + + - + ob_get_length Return the length of the output buffer - - Description + + + &reftitle.description; intob_get_length - This will return the length of the contents in the output buffer - or &false;, if output buffering isn't active. + This will return the length of the contents in the output buffer. + + + + &reftitle.returnvalues; + + Returns the length of the output buffer contents or &false; if no + buffering is active. + + + + + &reftitle.examples; A simple <function>ob_get_length</function> example @@ -39,23 +50,26 @@ echo $len1 . ", ." . $len2; ?> ]]> - - Our example will output: - + &example.outputs; + + + + &reftitle.seealso; - See also ob_start and - ob_get_contents. + + ob_start + ob_get_contents + + - + ob_get_level Return the nesting level of the output buffering mechanism - - Description + + + &reftitle.description; intob_get_level - This will return the level of nested output buffering handlers - or zero if output buffering is not activated. - - - See also ob_start and - ob_get_contents. + Returns the nesting level of the output buffering mechanism. + + + &reftitle.returnvalues; + + Returns the level of nested output buffering handlers or zero if output + buffering is not active. + + + + + &reftitle.seealso; + + + ob_start + ob_get_contents + + + + + ob_get_status Get status of output buffers - - Description + + + &reftitle.description; arrayob_get_status bool full_status FALSE - ob_get_status returns status information on - either the top level output buffer or all active output buffer levels - if full_status is set to &true;. + ob_get_status returns status information on either + the top level output buffer or all active output buffer levels if + full_status is set to &true;. + + + + &reftitle.parameters; + + + + full_status + + + &true; to return all active output buffer levels. If &false, or not + set, only the top level output buffer is returned. + + + + + + + + + &reftitle.returnvalues; If called without the full_status parameter or with full_status = &false; a simple array with the following elements is returned: - - - Simple <function>ob_get_status</function> output - + + + 2 @@ -32,9 +53,9 @@ Array [name] => URL-Rewriter [del] => 1 ) - - - +]]> + + Simple <function>ob_get_status</function> results KeyValue @@ -51,10 +72,9 @@ Array The output level is used as key of the top level array and each array element itself is another array holding status information on one active output level. - - - Full <function>ob_get_status</function> output - + + + Array @@ -81,8 +101,10 @@ Array ) ) - - +]]> + + + The full output contains these additional elements: @@ -93,11 +115,18 @@ Array blocksize... + + + + &reftitle.seealso; - See also ob_get_level and - ob_list_handlers. + + ob_get_level + ob_list_handlers + + - + ob_gzhandler ob_start callback function to gzip output buffer - - Description + + + &reftitle.description; stringob_gzhandler stringbuffer intmode - - - ob_gzhandler requires the zlib - extension. - - - ob_gzhandler is intended to be used as a - callback function for ob_start to help - facilitate sending gz-encoded data to web browsers that support - compressed web pages. Before ob_gzhandler - actually sends compressed data, it determines what type of - content encoding the browser will accept ("gzip", "deflate" or - none at all) and will return its output accordingly. All - browsers are supported since it's up to the browser to send the - correct header saying that it accepts compressed web pages. - If a browser doesn't support compressed pages this function returns - &false;. + ob_gzhandler is intended to be used as a callback + function for ob_start to help facilitate sending + gz-encoded data to web browsers that support compressed web pages. + Before ob_gzhandler actually sends compressed data, + it determines what type of content encoding the browser will accept + ("gzip", "deflate" or none at all) and will return its output accordingly. + All browsers are supported since it's up to the browser to send the + correct header saying that it accepts compressed web pages. If a browser + doesn't support compressed pages this function returns &false;. - - - mode was added in PHP 4.0.5. - - + + + + &reftitle.parameters; + + + + buffer + + + + + + + mode + + + + + + + + + + + &reftitle.returnvalues; + + + + + + + &reftitle.changelog; + + + + + + &Version; + &Description; + + + + + 4.0.5 + + The mode parameter was added. + + + + + + + + + + &reftitle.examples; <function>ob_gzhandler</function> example @@ -56,22 +100,37 @@ ob_start("ob_gzhandler"); + + + + &reftitle.notes; - You cannot use both ob_gzhandler and - - zlib.output_compression. Also note that - using + ob_gzhandler requires the zlib extension. + + + + + You cannot use both ob_gzhandler and zlib.output_compression. + Also note that using zlib.output_compression is preferred over ob_gzhandler. + + + + &reftitle.seealso; - See also - ob_start and - ob_end_flush. + + ob_start + ob_end_flush + + - + ob_implicit_flush Turn implicit flush on/off - - Description + + + &reftitle.description; voidob_implicit_flush intflag - ob_implicit_flush will turn implicit - flushing on or off (if no flag is given, - it defaults to on). Implicit flushing will result in a flush - operation after every output call, so that explicit calls to - flush will no longer be needed. - - - See also flush, - ob_start, and - ob_end_flush. + ob_implicit_flush will turn implicit flushing on or + off. Implicit flushing will result in a flush operation after every output + call, so that explicit calls to flush will no longer + be needed. + + + &reftitle.parameters; + + + + flag + + + &true; to turn implicit flushing on, &false; otherwise. + Defaults to &true;. + + + + + + + + + &reftitle.returnvalues; + + &return.void; + + + + + &reftitle.seealso; + + + flush + ob_start + ob_end_flush + + + + + ob_list_handlers List all output handlers in use - - Description + + + &reftitle.description; arrayob_list_handlers - This will return an array with the output handlers in use (if any). If - output_buffering is - enabled or an anonymous function was used with - ob_start, ob_list_handlers will - return "default output handler". + Lists all output handlers in use. + + + + &reftitle.returnvalues; + + This will return an array with the output handlers in use (if any). If + output_buffering is enabled or + an anonymous function was used with ob_start, + ob_list_handlers will return "default output + handler". + + + + + &reftitle.examples; <function>ob_list_handlers</function> example @@ -61,14 +72,20 @@ Array + + + + &reftitle.seealso; - See also - ob_end_clean, - ob_end_flush, - ob_get_flush, - ob_start. + + ob_end_clean + ob_end_flush + ob_get_flush + ob_start + + - + ob_start Turn on output buffering - - Description + + + &reftitle.description; boolob_start callbackoutput_callback @@ -15,52 +15,17 @@ boolerase - This function will turn output buffering on. While output - buffering is active no output is sent from the script (other than - headers), instead the output is stored in an internal buffer. + This function will turn output buffering on. While output buffering is + active no output is sent from the script (other than headers), instead the + output is stored in an internal buffer. - The contents of this internal buffer may be copied into a string - variable using ob_get_contents. To output - what is stored in the internal buffer, use - ob_end_flush. Alternatively, - ob_end_clean will silently discard the - buffer contents. + The contents of this internal buffer may be copied into a string variable + using ob_get_contents. To output what is stored in + the internal buffer, use ob_end_flush. Alternatively, + ob_end_clean will silently discard the buffer + contents. - - An optional output_callback function may - be specified. This function takes a string as a parameter and - should return a string. The function will be called when - ob_end_flush is called, or when the output - buffer is flushed to the browser at the end of the request. When - output_callback is called, it will receive - the contents of the output buffer as its parameter and is - expected to return a new output buffer as a result, which will be - sent to the browser. If the output_callback is not - a callable function, this function will return &false;. - If the callback function has two parameters, the second parameter is filled - with a bit-field consisting of - PHP_OUTPUT_HANDLER_START, - PHP_OUTPUT_HANDLER_CONT and - PHP_OUTPUT_HANDLER_END. - If output_callback returns &false; original input - is sent to the browser. - - - - In PHP 4.0.4, ob_gzhandler was introduced - to facilitate sending gz-encoded data to web browsers that - support compressed web pages. ob_gzhandler - determines what type of content encoding the browser will accept - and will return its output accordingly. - - - - - Before PHP 4.3.2 this function did not return &false; in case the passed - output_callback can not be executed. - - Some web servers (e.g. Apache) change the working directory of a script @@ -69,17 +34,6 @@ callback function. - - If the optional parameter chunk_size is passed, the - callback function is called on every first newline after - chunk_size bytes of output. - The output_callback parameter may be bypassed by - passing a &null; value. - - - If the optional parameter erase is set to &false;, - the buffer will not be deleted until the script finishes (as of PHP 4.3.0). - Output buffers are stackable, that is, you may call ob_start while another @@ -89,19 +43,122 @@ functions are active, output is being filtered sequentially through each of them in nesting order. + + + + &reftitle.parameters; - ob_end_clean, - ob_end_flush, ob_clean, - ob_flush and ob_start - may not be called from a callback function. If you call them from - callback function, the behavior is undefined. If you would like to - delete the contents of a buffer, return "" (a null string) from callback - function. - You can't even call functions using the output buffering functions like - print_r($expression, true) or - highlight_file($filename, true) from a callback - function. + + + output_callback + + + An optional output_callback function may be + specified. This function takes a string as a parameter and should + return a string. The function will be called when + ob_end_flush is called, or when the output buffer + is flushed to the browser at the end of the request. When + output_callback is called, it will receive the + contents of the output buffer as its parameter and is expected to + return a new output buffer as a result, which will be sent to the + browser. If the output_callback is not a + callable function, this function will return &false;. + + + If the callback function has two parameters, the second parameter is + filled with a bit-field consisting of + PHP_OUTPUT_HANDLER_START, + PHP_OUTPUT_HANDLER_CONT and + PHP_OUTPUT_HANDLER_END. + + + If output_callback returns &false; original + input is sent to the browser. + + + The output_callback parameter may be bypassed + by passing a &null; value. + + + ob_end_clean, ob_end_flush, + ob_clean, ob_flush and + ob_start may not be called from a callback + function. If you call them from callback function, the behavior is + undefined. If you would like to delete the contents of a buffer, + return "" (a null string) from callback function. + You can't even call functions using the output buffering functions like + print_r($expression, true) or + highlight_file($filename, true) from a callback + function. + + + + In PHP 4.0.4, ob_gzhandler was introduced to + facilitate sending gz-encoded data to web browsers that support + compressed web pages. ob_gzhandler determines + what type of content encoding the browser will accept and will return + its output accordingly. + + + + + + chunk_size + + + If the optional parameter chunk_size is passed, the + callback function is called on every first newline after + chunk_size bytes of output. + + + + + erase + + + If the optional parameter erase is set to &false;, + the buffer will not be deleted until the script finishes (as of PHP 4.3.0). + + + + + + + + &reftitle.returnvalues; + + &return.success; + + + + + &reftitle.changelog; + + + + + + &Version; + &Description; + + + + + 4.3.2 + + This function was changed to return &false; in case the passed + output_callback can not be executed. + + + + + + + + + + &reftitle.examples; User defined callback function example @@ -130,9 +187,7 @@ ob_end_flush(); ?> ]]> - - Would produce: - + &example.outputs; @@ -144,16 +199,24 @@ ob_end_flush(); - - See also ob_get_contents, - ob_end_flush, - ob_end_clean, - ob_implicit_flush, - ob_gzhandler, ob_iconv_handler - mb_output_handler, and - ob_tidyhandler. - + + + &reftitle.seealso; + + + ob_get_contents + ob_end_clean + ob_end_flush + ob_implicit_flush + ob_gzhandler + ob_iconv_handler + mb_output_handler + ob_tidyhandler + + + + + output_add_rewrite_var Add URL rewriter values - - Description + + + &reftitle.description; booloutput_add_rewrite_var stringname @@ -31,6 +32,41 @@ not active already. + + + + &reftitle.parameters; + + + + name + + + The variable name. + + + + + value + + + The variable value. + + + + + + + + + &reftitle.returnvalues; + + &return.success; + + + + + &reftitle.examples; <function>output_add_rewrite_var</function> example @@ -71,13 +107,19 @@ Array - - See also - output_reset_rewrite_vars, - ob_flush and - ob_list_handlers. - + + + &reftitle.seealso; + + + output_reset_rewrite_vars + ob_flush + ob_list_handlers + + + + + output_reset_rewrite_vars Reset URL rewriter values - - Description + + + &reftitle.description; booloutput_reset_rewrite_vars @@ -17,6 +18,17 @@ function or the session mechanism (if session.use_trans_sid was set on session_start). + + + + &reftitle.returnvalues; + + &return.success; + + + + + &reftitle.examples; <function>output_reset_rewrite_vars</function> example @@ -43,14 +55,20 @@ echo 'link'; - - See also - output_add_rewrite_var, - ob_flush, - ob_list_handlers and - session_start. - + + + &reftitle.seealso; + + + output_add_rewrite_var + ob_flush + ob_list_handlers + session_start + + + +