diff --git a/appendices/migration54.xml b/appendices/migration54.xml index 5e331e58d3..6e2b09318b 100644 --- a/appendices/migration54.xml +++ b/appendices/migration54.xml @@ -158,6 +158,17 @@ level error is emitted. + + + The third parameter of ob_start has changed from + boolean erase to integer + flags. Note that code that explicitly set + erase to &false; will no longer behave as expected + in PHP 5.4: please follow + this example to write + code that is compatible with PHP 5.3 and 5.4. + + The following keywords are now reserved, and may not be used diff --git a/reference/outcontrol/constants.xml b/reference/outcontrol/constants.xml index 151cfaaae2..088feacd27 100644 --- a/reference/outcontrol/constants.xml +++ b/reference/outcontrol/constants.xml @@ -102,6 +102,68 @@ + + + PHP_OUTPUT_HANDLER_CLEANABLE + (integer) + + + + Controls whether an output buffer created by + ob_start can be cleaned. + + + Available since PHP 5.4. + + + + + + PHP_OUTPUT_HANDLER_FLUSHABLE + (integer) + + + + Controls whether an output buffer created by + ob_start can be flushed. + + + Available since PHP 5.4. + + + + + + PHP_OUTPUT_HANDLER_REMOVABLE + (integer) + + + + Controls whether an output buffer created by + ob_start can be removed before the end of the script. + + + Available since PHP 5.4. + + + + + + PHP_OUTPUT_HANDLER_STDFLAGS + (integer) + + + + The default set of output buffer flags; currently equivalent to + PHP_OUTPUT_HANDLER_CLEANABLE | + PHP_OUTPUT_HANDLER_FLUSHABLE | + PHP_OUTPUT_HANDLER_REMOVABLE. + + + Available since PHP 5.4. + + + diff --git a/reference/outcontrol/functions/ob-start.xml b/reference/outcontrol/functions/ob-start.xml index 39d9856c48..a610242fff 100644 --- a/reference/outcontrol/functions/ob-start.xml +++ b/reference/outcontrol/functions/ob-start.xml @@ -10,9 +10,9 @@ &reftitle.description; boolob_start - callableoutput_callback + callableoutput_callback&null; intchunk_size0 - boolerasetrue + intflagsPHP_OUTPUT_HANDLER_STDFLAGS This function will turn output buffering on. While output buffering is @@ -140,13 +140,56 @@ - erase + flags - If the optional parameter erase is set to &false;, - the buffer will not be deleted until the script finishes. - This causes that flushing and cleaning functions would issue a notice - and return &false; if called. + The flags parameter is a bitmask that controls + the operations that can be performed on the output buffer. The default + is to allow output buffers to be cleaned, flushed and removed, which + can be set explicitly via + PHP_OUTPUT_HANDLER_CLEANABLE | + PHP_OUTPUT_HANDLER_FLUSHABLE | + PHP_OUTPUT_HANDLER_REMOVABLE, or + PHP_OUTPUT_HANDLER_STDFLAGS as shorthand. + + + Each flag controls access to a set of functions, as described below: + + + + + Constant + Functions + + + + + PHP_OUTPUT_HANDLER_CLEANABLE + + ob_clean, + ob_end_clean, and + ob_get_clean. + + + + PHP_OUTPUT_HANDLER_FLUSHABLE + + ob_end_flush, + ob_flush, and + ob_get_flush. + + + + PHP_OUTPUT_HANDLER_REMOVABLE + + ob_end_clean, + ob_end_flush, and + ob_get_flush. + + + + + @@ -173,6 +216,21 @@ + + 5.4.0 + + The third parameter of ob_start changed from a + boolean parameter called erase + (which, if set to &false;, would prevent the output buffer from being + deleted until the script finished executing) to an + integer parameter called flags. + Unfortunately, this results in an API compatibility break for code + written prior to PHP 5.4.0 that uses the third parameter. See + the flags example + for an example of how to handle this with code that needs to be + compatible with both. + + 5.4.0 @@ -241,6 +299,26 @@ ob_end_flush(); + + + + Creating an uneraseable output buffer in a way compatible with both PHP 5.3 and 5.4 + +=')) { + ob_start(null, 0, PHP_OUTPUT_HANDLER_STDFLAGS ^ + PHP_OUTPUT_HANDLER_REMOVABLE); +} else { + ob_start(null, 0, false); +} + +?> +]]> + + +