(PHP 4, PHP 5)
ob_start — Enclenche la tamporisation de sortie
Cette fonction démarre la tamporisation 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.
Une fonction optionnelle de rappel peut être spécifiée. ob_start() prend une chaîne comme paramètre, et retourne une chaîne. Elle sera appelée par ob_end_flush() ou lorsque le tampon sera envoyé au navigateur à la fin du script et recevra le contenu du tampon de sortie. Lorsque la fonction output_callback est appelée, elle doit retourner un nouveau contenu pour le tampon de sortie : celui-ci sera envoyé au navigateur. Si output_callback n'est pas une fonction accessible, la fonction retournera FALSE.
Si la fonction de rappel a deux paramètres, le second est composé du champ bits constitué par PHP_OUTPUT_HANDLER_START, PHP_OUTPUT_HANDLER_CONT et PHP_OUTPUT_HANDLER_END.
Si output_callback retourne FALSE, l'entrée originale est envoyée au navigateur.
Le paramètre output_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) comme fonction de rappel. Vous ne pourrez jamais appeler les fonctions utilisant la fonction de tamporisation de sortie comme print_r($expression, true) ou highlight_file($filename, true) depuis une fonction de rappel.
Note: En PHP 4.0.4, 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.
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 (zéro) signifie que la fonction est appelée uniquement à la fin, et si la valeur est 1, chunk_size vaudra 4096.
Si le paramètre optionnel erase est défini à FALSE, le tampon ne sera pas effacé tant que le script ne sera pas terminé (depuis PHP 4.3.0).
Cette fonction retourne TRUE en cas de succès, FALSE en cas d'échec.
| Version | Description |
|---|---|
| 4.3.2 | Cette fonction a été modifiée pour retourner FALSE dans le cas où output_callback ne peut être exécuté. |
Exemple #1 Exemple de gestion de sortie avec fonction de rappel
<?php
function rappel($buffer)
{
// remplace toutes les pommes par des carottes
return (ereg_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>