(PHP 4, PHP 5, PHP 7)
ob_start — Ausgabepufferung aktivieren
$output_callback = NULL
[, int $chunk_size = 0
[, int $flags = PHP_OUTPUT_HANDLER_STDFLAGS
]]] ) : boolDiese Funktion aktiviert die Ausgabepufferung. Während die Ausgabepufferung aktiv ist, werden Skriptausgaben (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. Um auszugeben, was im internen Puffer gespeichert ist, ist ob_end_flush() zu verwenden. Alternativ wird mit ob_end_clean() der Puffer stillschweigend verworfen.
Einige Webserver (z.B. Apache) ändern das Arbeitsverzeichnis des Skripts vor dem Aufruf der Callback-Funktion. Bei Bedarf kann mit Hilfe von beispielsweise chdir(dirname($_SERVER['SCRIPT_FILENAME'])) wieder in das Scriptverzeichnis zurückgewechselt werden.
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, dass Sie später auch ob_end_flush() entsprechend oft aufrufen. Sind mehrere Callback-Funktionen aktiv, so werden die Ausgaben der Reihe nach von Ausgabepuffer zu Ausgabepuffer weitergegeben, und die Callback-Funktionen in Verschachtelungsreihenfolge aufgerufen.
output_callback
Optional kann eine output_callback Funktion angegeben
werden. Diese Funktion nimmt eine Zeichenkette als Parameter entgegen, und
sollte eine Zeichenkette zurückliefern. Die Funktion wird aufgerufen, wenn
der Ausgabepuffer geleert (gesendet) oder bereinigt wird (mit
ob_flush(), ob_clean() oder einer
ähnlichen Funktion), oder wenn der Ausgabepuffer am Ende der Anfrage zum
Browser gesendet wird.
Wenn output_callback aufgerufen wird, dann empfängt
es den Inhalt des Ausgabepuffers als Parameter, und sollte einen neuen
Ausgabepuffer als Ergebnis zurückgeben, der an den Browser gesendet wird.
Ist output_callback keine aufrufbare Funktion, gibt
diese Funktion FALSE zurück.
Dies ist die Signatur des Callbacks:
$buffer
[, int $phase
] ) : stringbufferphasePHP_OUTPUT_HANDLER_* Konstanten.
Gibt output_callback FALSE zurück, wird die ursprüngliche
Eingabe an den Browser gesendet.
Um den Parameter output_callback auszulassen, kann
ein NULL-Wert übergeben werden.
ob_end_clean(), ob_end_flush(), ob_clean(), ob_flush() und ob_start() können innerhalb einer Callback-Funktion nicht aufgerufen werden; das Ergebnis eines solchen Aufrufs ist nicht definiert. Wenn Sie den Inhalt eines Puffers löschen wollen, so gegeben Sie einfach "" (eine leere Zeichenkette) aus der Callback-Funktion 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 aufgerufen werden.
Hinweis:
Die Funktion ob_gzhandler() existiert, um es zu ermöglichen gz-kodierte Daten an Webbrowser zu senden, die komprimierte Webseiten unterstützen. ob_gzhandler() ermittelt welche Art von Inhaltskodierung der Browser akzeptiert, und liefert seine Ausgabe entsprechend.
chunk_size
Wird der optionale Parameter chunk_size übergeben,
dann wird der Puffer nach jedem Ausgabeaufruf geleert, der dazu führt, dass
die Länge des Puffers größer oder gleich chunk_size
ist. Der Vorgabewert 0 bedeutet, dass die Ausgabefunktion
nur aufgerufen wird, wenn der Ausgabepuffer geschlossen wird.
Vor PHP 5.4.0 war der Wert 1 ein Sonderfall, der die Datenblockgröße auf 4096 Bytes festlegte.
flags
Beim Parameter flags handelt es sich um eine Bitmaske,
die die Operationen steuert, die mit dem Ausgabepuffer durchgeführt werden
können. Vorgabe ist es zu erlauben, dass Ausgabepuffer bereinigt, geleert
und entfernt werden dürfen, was ausdrücklich mit
PHP_OUTPUT_HANDLER_CLEANABLE |
PHP_OUTPUT_HANDLER_FLUSHABLE |
PHP_OUTPUT_HANDLER_REMOVABLE, oder
PHP_OUTPUT_HANDLER_STDFLAGS als Abkürzung, eingestellt
werden kann.
Jedes Flag steuert den Zugriff auf einen Satz von Funktionen, wie im Folgenden beschrieben:
| Konstante | Funktionen |
|---|---|
PHP_OUTPUT_HANDLER_CLEANABLE
|
ob_clean(), ob_end_clean(), und ob_get_clean(). |
PHP_OUTPUT_HANDLER_FLUSHABLE
|
ob_end_flush(), ob_flush(), und ob_get_flush(). |
PHP_OUTPUT_HANDLER_REMOVABLE
|
ob_end_clean(), ob_end_flush(), und ob_get_flush(). |
Gibt bei Erfolg TRUE zurück. Im Fehlerfall wird FALSE zurückgegeben.
| 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 solche Fehler zu verarbeiten.
|
| 5.4.0 |
Der dritte Parameter der Funktion ob_start() wurde von
einem Paramter erase vom Typ boolean
(der, wenn auf FALSE gesetzt, verhindert, dass der Ausgabepuffer vor dem
Skriptende gelöscht werden konnte) zu einem integer Parameter
namens flags geändert. Leider resultiert dies in einem
API-Kompatibilitätsbruch für Code, der vor PHP 5.4.0 geschrieben wurde, und
den dritten Parameter nutzt.
Im Flags-Beispiel wird
gezeigt, wie entsprechender Code geschrieben werden kann, der mit beiden
Versionen kompatibel sein muss.
|
| 5.4.0 | Eine Datenblockgröße von 1 bewirkt nun, dass Datenblöcke von 1 Byte an den Ausgabepuffer gesendet werden. |
| 4.3.2 |
Diese Funktion wurde derart geändert, dass FALSE zurückgegeben wird, falls
der übergebene output_callback nicht ausgeführt
werden kann.
|
Beispiel #1 Beispiel einer benutzerkonfigurierten Callbackfunktion
<?php
function callback($buffer)
{
// ersetzt alle Ä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 Erzeugen eines nicht löschbaren Ausgabepuffers auf eine Weise, die mit PHP 5.3 und 5.4 kompatibel ist
<?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);
}
?>