La bufferisation de sortie au niveau utilisateur de PHP peut commencé, manipulé et terminé depuis le code PHP. Chacun de ces tampons inclut un tampon de sortie et une fonction de gestion de sortie associée.
Les tampons de sortie au niveau utilisateur peuvent être démarrés en utilisant la fonction ob_start() ou en définissant les paramètres output_buffering et output_handler de php.ini. Tant l'un que l'autre peuvent créer des tampons de sortie, ob_start() est plus flexible car il accepte des fonctions définies par l'utilisateur comme gestionnaires de sortie et les opérations autorisées sur le tampon (flush, clean, remove) peuvent être définies également. Les tampons de sortie démarrés avec ob_start() seront actifs à partir de la ligne où la fonction a été appelée, tandis que ceux démarrés avec output_buffering bufferiseront la sortie à partir de la première ligne du script.
PHP est également livré avec un gestionnaire de sortie intégré "URL-Rewriter"
qui démarre son propre tampon de sortie et ne permet que deux instances de celui-ci
à fonctionner en même temps
(une pour la réécriture d'URL au niveau utilisateur
et une pour le support transparent des identifiants de session).
Ces tampons peuvent être démarrés en appelant
la fonction output_add_rewrite_var()
et/ou en activant le paramètre
session.use_trans_sid
de php.ini.
L'extension zlib
a son propre tampon de sortie
qui peut être activé en utilisant le paramètre
zlib.output_compression
de php.ini.
Note: Tant que
"URL-Rewriter"
est spécial en ce qu'il ne permet que deux instances de celui-ci à fonctionner en même temps, tous les tampons de sortie au niveau utilisateur utilisent les mêmes tampons sous-jacents utilisés par ob_start() avec leur fonctionnalité implémentée par une fonction de gestion de sortie personnalisée. En tant que tel, toute leur fonctionnalité peut être émulée par du code utilisateur.
Laver envoie et supprime le contenu du tampon actif. Les tampons de sortie sont lavés lorsque la taille de la sortie dépasse la taille du tampon, le script se termine ou ob_flush(), ob_end_flush(), ou ob_get_flush() est appelé.
Appeler ob_end_flush() ou ob_get_flush() désactivera le tampon actif.
Laver les tampons va laver la valeur de retour du gestionnaire de sortie qui peut différer du contenu du tampon. Par exemple, utiliser ob_gzhandler() va compresser la sortie et laver la sortie compressée.
Le contenu du tampon actif peut être récupéré en appelant ou ob_get_flush().
Si seule la longueur du contenu du tampon est nécessaire, ob_get_length() ou ob_get_status() va retourner la longueur du contenu en octets.
Appeler ob_get_clean() ou ob_get_flush() désactivera le tampon actif après avoir retourné son contenu.
Le contenu du tampon actif peut être nettoyé en appelant ob_clean(), ob_end_clean() ou ob_get_clean().
Appeler ob_end_clean() ou ob_get_clean() désactivera le tampon actif.
Les tampons de sortie peuvent être désactivés en appelant ob_end_clean(), ob_end_flush(), ob_get_flush() ou ob_get_clean().
Les tampons de sortie démarrés sans le drapeau
PHP_OUTPUT_HANDLER_REMOVABLE
ne peuvent pas être désactivés et généreront une E_NOTICE
.
Chaque tampon de sortie qui n'a pas été désactivé à la fin du script ou lorsque exit() est appelé sera lavé et désactivé par le processus de terminaison de PHP. Les tampons seront lavés et désactivés dans l'ordre inverse de leur démarrage. Le dernier tampon démarré sera le premier, le premier tampon démarré sera le dernier à être lavé et désactivé.
Si le vidage de tampon du contenu du tampon n'est pas désiré, un gestionnaire de sortie personnalisé doit être utilisé pour empêcher le vidage de tampon lors de la fermeture.
Si une exception non capturée est lancée dans un gestionnaire de sortie
le programme se termine et le gestionnaire est invoqué
par le processus de terminaison après quoi
le message d'erreur "Uncaught Exception"
est retourné.
Si l'exception non capturée est lancée dans un gestionnaire invoqué par ob_flush(), ob_end_flush() ou ob_get_flush(), le contenu du tampon est lavé avant le message d'erreur.
Si une exception non capturée est lancée dans un gestionnaire de sortie pendant la terminaison, le gestionnaire est terminé et ni le contenu du tampon ni le message d'erreur ne sont lavés.
Note: Si un gestionnaire lance une exception son drapeau
PHP_OUTPUT_HANDLER_DISABLED
est défini.
Si une erreur non fatale est levée dans un gestionnaire de sortie le programme continue son exécution.
Si une erreur non fatale est levée dans un gestionnaire invoqué par
ob_flush(), ob_end_flush()
ou ob_get_flush(),
le tampon vide certaines données en fonction de la valeur de retour du gestionnaire.
Si le gestionnaire retourne false
le tampon et le message d'erreur sont lavés.
Si le gestionnaire retourne autre chose, la valeur de retour du gestionnaire est lavée
mais pas le message d'erreur.
Note: Si un gestionnaire retourne
false
son drapeauPHP_OUTPUT_HANDLER_DISABLED
est défini.
Si une erreur fatale est levée dans un gestionnaire de sortie le programme se termine et le gestionnaire est invoqué par le processus de terminaison après quoi le message d'erreur est lavé.
Si l'erreur fatale est levée dans un gestionnaire invoqué par ob_flush(), ob_end_flush() ou ob_get_flush(), le contenu du tampon est lavé avant le message d'erreur.
Si une erreur fatale est levée dans un gestionnaire de sortie pendant la terminaison le programme se termine sans laver le contenu du tampon ou le message d'erreur.
Dans des circonstances spécifiques, la sortie produite dans le gestionnaire est lavée avec le contenu du tampon. Cette sortie n'est pas ajoutée au tampon et ne fait pas partie de la chaîne retournée par ob_get_flush().
Durant les opérations de vidage de tampon (appel de ob_flush(),
ob_end_flush(), ob_get_flush()
et pendant la terminaison)
si la valeur de retour d'un gestionnaire est false
le contenu du tampon est lavé suivi de la sortie.
Si le gestionnaire n'est pas invoqué pendant la terminaison
le gestionnaire lançant une exception ou l'appel de exit()
résulte dans le même comportement.
Note: Si un gestionnaire retourne
false
son drapeauPHP_OUTPUT_HANDLER_DISABLED
est défini.
Les
drapeaux d'état des gestionnaires
du masque de bits flags
du tampon
sont définis à chaque invocation du gestionnaire de sortie
et font partie du masque de bits flags
retourné par
ob_get_status().
Si le gestionnaire exécute avec succès et ne retourne pas false
,
PHP_OUTPUT_HANDLER_STARTED
et
PHP_OUTPUT_HANDLER_PROCESSED
sont définis.
Si le gestionnaire retourne false
ou lance une exception pendant l'exécution,
PHP_OUTPUT_HANDLER_STARTED
et
PHP_OUTPUT_HANDLER_DISABLED
sont définis.
Note: Si
PHP_OUTPUT_HANDLER_DISABLED
d'un gestionnaire est défini, le gestionnaire ne sera pas invoqué en appelant ob_end_clean(), ob_end_flush(), ob_get_clean(), ob_get_flush() ob_get_clean(), ob_get_flush(), ob_clean(), ob_flush() ou pendant le processus de terminaison de PHP. Avant PHP 8.4.0, ce drapeau n'avait aucun effet lors de l'appel de la fonction ob_clean() ou ob_flush().