PHP-Handbuch: Ausgabepufferung aktivieren

Beschreibung

bool ob_start ([ callable $output_callback = NULL [, int $chunk_size = 0 [, int $flags = PHP_OUTPUT_HANDLER_STDFLAGS ]]] )

Diese Funktion aktiviert die Ausgabepufferung. Während die Ausgabepufferung aktiv ist werden Scriptausgaben (mit Ausnahme von Headerinformationen) nicht direkt an den Client weitergegeben sondern in einem internen Puffer gesammelt.

Der Inhalt dieses internen Puffers kann mit Hilfe der Funktion ob_get_contents in eine Stringvariable kopiert werden. Mit der Funktion ob_end_flush können die Pufferinhalte an den Client ausgegeben werden, ob_end_clean wird der Puffer ohne Ausgabe gelöscht.

Warnung

Einige Webserver (z.B. Apache) ändern das Arbeitsverzeichnis des Scripts vor dem Aufruf der Callback-Funktion am Scriptende. Sie können falls nötig mit Hilfe von chdir(dirname($_SERVER['SCRIPT_FILENAME'])) wieder in das Scriptverzeichnis zurückwechseln.

Ausgabepuffer können verschachtelt werden, d.h. Sie können ob_start erneut aufrufen während bereits ein anderer ob_start Aufruf aktiv ist. Sie müssen nur sicher stellen das Sie später auch ob_end_flush entsprechend oft aufrufen. Sind mehrere Callback-Funktion aktiv so werden die Ausgaben der Reihe nach von Ausgabepuffer zu Ausgabepuffer weitergegeben und die Callback-Funktionen in Verschachtelungsreihenfolge aufgerufen.

Parameter-Liste

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 the output buffer is flushed (sent) or cleaned (with ob_flush, ob_clean or similar function) 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. This is the callback signature:

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

buffer: Contents of the output buffer.
phase: Bitmask of PHP_OUTPUT_HANDLER_* constants.

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 und ob_start können innerhalb einer Callback-Funktion nicht benutzt werden, das Ergebnis eines solchen Aufrufs ist nicht definiert. Wenn Sie den Inhalt eines Puffers aus einem Callback löschen wollen so gegeben Sie einfach den Leerstring "" zurück. Auch Funktionen wie print_r($expression, true) oder highlight_file($filename, true) die den Ausgabepuffermechanismus intern nutzen können innerhalb eines Callbacks nicht benutzt werden.

Hinweis:
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 buffer will be flushed after any output call which causes the buffer's length to equal or exceedchunk_size. The default value 0 means that the output function will only be called when the output buffer is closed.

Prior to PHP 5.4.0, the value 1 was a special case value that set the chunk size to 4096 bytes.

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 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.

Rückgabewerte

Gibt bei Erfolg TRUE zurück. Im Fehlerfall wird FALSE zurückgegeben.

Changelog

Version	Beschreibung
7.0.0	Falls ob_start innerhalb eines bereits aktiven Callbacks aufgerufen wird, erzeugt diese Funktion nicht länger den Fehler `E_ERROR` sondern `E_RECOVERABLE_ERROR`. Dies erlaubt es eigenen Funktionen zur Fehlerbehandlung diesen Fehler zu verarbeiten.
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	A chunk size of 1 now results in chunks of 1 byte being sent to the output buffer.
4.3.2	This function was changed to return `FALSE` in case the passed `output_callback` can not be executed.

Beispiele

Beispiel #1 Beispiel einer benutzerkonfigurierten Callbackfunktion


<?php

function callback($buffer)
{
  // ersetzt Äpfel mit Birnen
  return (str_replace("Äpfel", "Birnen", $buffer));
}

ob_start("callback");

?>
<html>
<body>
<p>Das ist wie Äpfel mit Birnen zu vergleichen.</p>
</body>
</html>
<?php

ob_end_flush();

?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

<html>
<body>
<p>Das ist wie Birnen mit Birnen zu vergleichen.</p>
</body>
</html>

Beispiel #2 Creating an uneraseable output buffer in a way compatible with both PHP 5.3 and 5.4


<?php

if (version_compare(PHP_VERSION, '5.4.0', '>=')) {
  ob_start(null, 0, PHP_OUTPUT_HANDLER_STDFLAGS ^
    PHP_OUTPUT_HANDLER_REMOVABLE);
} else {
  ob_start(null, 0, false);
}

?>

Siehe auch

ob_get_contents
ob_end_flush
ob_end_clean
ob_implicit_flush
ob_gzhandler
ob_iconv_handler
mb_output_handler
ob_tidyhandler.