Home/ Manual/ outcontrol / functions/ ob_start

ob_start

PHP function Edit on GitHub ✎

(PHP 4, PHP 5, PHP 7, PHP 8)

Turn on output buffering

Description

ob_start(callable|null $callback = null, int $chunk_size = 0, int $flags = PHP_OUTPUT_HANDLER_STDFLAGS): bool

This function will turn output buffering on. While output buffering is active no output is sent from the script, instead the output is stored in an internal buffer. See outcontrol.what-output-is-buffered on exactly what output is affected.

Output buffers are stackable, that is, ob_start() may be called while another buffer is active. If multiple output buffers are active, output is being filtered sequentially through each of them in nesting order. See outcontrol.nesting-output-buffers for more details.

See outcontrol.user-level-output-buffers for a detailed description of output buffers.

Parameters

callback

An optional callback callable may be specified. It can also be bypassed by passing null.

callback is invoked when the output buffer is flushed (sent), cleaned, or when the output buffer is flushed at the end of the script.

The signature of the callback is as follows:

handler(string $buffer, [int $phase]): string

buffer: Contents of the output buffer.
phase: Bitmask of PHP_OUTPUT_HANDLER_* constants. See outcontrol.flags-passed-to-output-handlers for more details.

If callback returns false the contents of the buffer are returned. See outcontrol.output-handler-return-values for more details.

Warning

Calling any of the following functions from within an output handler will result in a fatal error: ob_clean(), ob_end_clean(), ob_end_flush(), ob_flush(), ob_get_clean(), ob_get_flush(), ob_start().

See outcontrol.output-handlers and outcontrol.working-with-output-handlers for more details on callbacks (output handlers).

chunk_size

If the optional parameter chunk_size is passed, the buffer will be flushed after any block of code resulting in output that causes the buffer's length to equal or exceed chunk_size. The default value 0 means that all output is buffered until the buffer is turned off. A value of 1 means the buffer will be flushed after every output operation, effectively disabling buffering. chunk_size also determines the initial size of the buffer reported by ob_get_status(): 16384 bytes when it is 0, and chunk_size rounded up to the next multiple of 4096 otherwise. See outcontrol.buffer-size for more details.

flags

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 the buffer control flags. See outcontrol.operations-on-buffers for more details.

Each flag controls access to a set of functions, as described below:

Constant	Functions
`PHP_OUTPUT_HANDLER_CLEANABLE`	`ob_clean()`
`PHP_OUTPUT_HANDLER_FLUSHABLE`	`ob_flush()`
`PHP_OUTPUT_HANDLER_REMOVABLE`	`ob_end_clean()`, `ob_end_flush()`, `ob_get_clean()`, `ob_get_flush()`

Note

Prior to PHP 8.4.0, the flags parameter could set the output handler status flags as well.

Return Values

Success

Changelog

Version	Description
8.5.0	Trying to produce output (e.g. with `echo()`) within the user output handler callback is now deprecated. The deprecation warning bypasses the handler and is output directly.

Examples

User defined callback function example

php

<?php

function callback($buffer)
{
  // replace all the apples with oranges
  return (str_replace("apples", "oranges", $buffer));
}

ob_start("callback");

?>
<html>
<body>
<p>It's like comparing apples to oranges.</p>
</body>
</html>
<?php

ob_end_flush();

?>

The above example will output:

output

<html>
<body>
<p>It's like comparing oranges to oranges.</p>
</body>
</html>

Creating an unerasable output buffer

php

<?php

ob_start(null, 0, PHP_OUTPUT_HANDLER_STDFLAGS ^ PHP_OUTPUT_HANDLER_REMOVABLE);

?>