(PHP 4, PHP 5, PHP 7, PHP 8)
ob_start — Enclenche la temporisation de sortie
$callback = null, int $chunk_size = 0, int $flags = PHP_OUTPUT_HANDLER_STDFLAGS): boolob_start() démarre la temporisation de sortie. Tant qu'elle est enclenchée, aucune donnée, hormis les en-têtes, n'est envoyée au navigateur, mais temporairement mise en tampon.
Le contenu de ce tampon peut être copié dans une chaîne avec la fonction ob_get_contents(). Pour afficher le contenu de ce tampon, utilisez ob_end_flush(). Au contraire, ob_end_clean() effacera le contenu de ce tampon.
Quelques serveurs web (par exemple Apache) modifient le dossier de
travail d'un script lorsqu'il appelle une fonction de rappel.
Vous pouvez revenir à un comportement normal en ajoutant
chdir(dirname($_SERVER['SCRIPT_FILENAME']))
dans votre fonction de rappel.
Les tampons de sortie sont gérés par pile, c'est-à-dire que vous pouvez appeler plusieurs fois ob_start() simultanément. Assurez-vous que vous appelez ob_end_flush() suffisamment souvent. Si plusieurs fonctions de rappel sont actives, les contenus seront filtrés séquentiellement, dans l'ordre d'emboîtement.
Si les tampons de sortie sont encore actif quand le script se termine, PHP affiche le contenu automatiquement.
callback
Une fonction optionnelle de rappel peut être spécifiée.
Cette fonction prend une chaîne comme paramètre, et
retourne une chaîne. Elle sera appelée lorsque le tampon sera envoyé
ou supprimé (avec les fonctions ob_flush(),
ob_clean() ou des fonctions similaires)
ou lorsque le tampon sera envoyé
au navigateur à la fin du script et recevra le contenu du tampon de
sortie. Lorsque la fonction callback est
appelée, elle doit retourner un nouveau contenu pour le tampon de sortie :
celui-ci sera envoyé au navigateur. Si callback
n'est pas une fonction accessible, la fonction retournera false.
Voici la signature de la fonction de rappel :
$buffer, int $phase = ?): stringbufferphasePHP_OUTPUT_HANDLER_*.
Si callback retourne false,
l'entrée originale est envoyée au navigateur.
Le paramètre callback peut être annulé
en y passant la valeur null.
ob_end_clean(), ob_end_flush(),
ob_clean(), ob_flush() et
ob_start() ne doivent pas être appelés depuis une
fonction de rappel. Si vous les appelez depuis une fonction de
rappel, le comportement ne sera pas défini. Si vous voulez effacer
le contenu du tampon, retournez "" (une chaîne vide) depuis la fonction
de rappel. Vous ne pourrez jamais appeler les fonctions utilisant
la fonction de temporisation de sortie comme
print_r($expression, true) ou
highlight_file($filename, true) depuis une fonction de
rappel.
Note:
La fonction ob_gzhandler() a été introduite pour faciliter l'envoi de fichiers compressés avec gzip aux navigateurs web qui supportent les pages compressées. ob_gzhandler() détermine le type d'encodage accepté par un navigateur, et retourne le contenu le plus adéquat.
chunk_size
Si le paramètre optionnel chunk_size est passé,
la fonction de rappel est appelée à chaque nouvelle ligne après
chunk_size octets d'affichage. La valeur
par défaut 0 (zéro) signifie que l'affichage
de la fonction ne sera appelé que lorsque le buffer de sortie est clos.
flags
Le paramètre flags est un masque qui contrôle
les opérations qui peuvent être effectuées sur le tampon de sortie.
Par défaut, il autorise le tampon de sortie à être nettoyé, envoyé
et supprimé, ce qui peut être défini explicitement avec les constantes
PHP_OUTPUT_HANDLER_CLEANABLE |
PHP_OUTPUT_HANDLER_FLUSHABLE |
PHP_OUTPUT_HANDLER_REMOVABLE, ou
PHP_OUTPUT_HANDLER_STDFLAGS comme alias.
Chaque drapeau contrôle l'accès à un jeu de fonctions, tel décrit ci-dessous :
| Constante | Fonctions |
|---|---|
PHP_OUTPUT_HANDLER_CLEANABLE |
ob_clean(), ob_end_clean() et ob_get_clean(). |
PHP_OUTPUT_HANDLER_FLUSHABLE |
ob_end_flush(), ob_flush() et ob_get_flush(). |
PHP_OUTPUT_HANDLER_REMOVABLE |
ob_end_clean(), ob_end_flush() et ob_get_flush(). |
Cette fonction retourne true en cas de succès ou false si une erreur survient.
Exemple #1 Exemple de gestion de sortie avec fonction de rappel
<?php
function rappel($buffer)
{
// remplace toutes les pommes par des carottes
return (str_replace("pommes de terre", "carottes", $buffer));
}
ob_start("rappel");
?>
<html>
<body>
<p>C'est comme comparer des carottes et des pommes de terre.</p>
</body>
</html>
<?php
ob_end_flush();
?>
L'exemple ci-dessus va afficher :
<html> <body> <p>C'est comme comparer des carottes et des carottes.</p> </body> </html>
Exemple #2 Crée un tampon de sortie in-effaçable
<?php
ob_start(null, 0, PHP_OUTPUT_HANDLER_STDFLAGS ^ PHP_OUTPUT_HANDLER_REMOVABLE);
?>