Tampons de sortie au niveau utilisateur

Sommaire

La bufferisation de sortie au niveau utilisateur de PHP peut être commencée, manipulée et terminée depuis le code PHP. Chacun de ces tampons inclut un tampon de sortie et une fonction de gestion de sortie associée.

Démarrer un tampon de sortie

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, accéder et nettoyer le contenu du tampon

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

Attention

Appeler ob_end_flush() ou ob_get_flush() désactivera le tampon actif.

Attention

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.

Attention

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

Attention

Appeler ob_end_clean() ou ob_get_clean() désactivera le tampon actif.

Désactiver les tampons

Les tampons de sortie peuvent être désactivés en appelant ob_end_clean(), ob_end_flush(), ob_get_flush() ou ob_get_clean().

Avertissement

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

Attention

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.

Exceptions lancées dans les gestionnaires de sortie

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.

Erreurs levées dans les gestionnaires de sortie

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

Sortie dans les gestionnaires de sortie

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 drapeau PHP_OUTPUT_HANDLER_DISABLED est défini.

Drapeaux d'état des gestionnaires de sortie

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