Fonction PHP ob_end_clean() : Tout ce que vous devez savoir

Quand PHP fonctionne avec la mise en tampon de sortie, tout ce que votre script envoie avec echo est collecté dans un tampon en mémoire au lieu d'être envoyé directement au navigateur. Parfois, vous souhaitez rejeter ce contenu capturé et arrêter complètement la mise en tampon — par exemple après avoir capturé quelque chose uniquement pour l'inspecter, ou lorsqu'une erreur signifie que la réponse partiellement construite ne doit jamais atteindre l'utilisateur. C'est exactement ce que fait ob_end_clean(). Cette page couvre sa syntaxe, sa valeur de retour, ses cas d'utilisation courants et ses différences avec les fonctions ob_* associées.

Qu'est-ce que la fonction ob_end_clean() ?

ob_end_clean() effectue deux opérations en un seul appel sur le tampon de sortie le plus haut (démarré en dernier) :

1. Supprime son contenu actuel — la sortie mise en tampon est supprimée, pas envoyée.
2. Désactive ce niveau de mise en tampon — le tampon est fermé et retiré de la pile.

La fonction existe depuis PHP 4. Le nom se décode comme output buffer (ob) — end — clean : « end » signifie fermer le niveau du tampon, « clean » signifie jeter le contenu (par opposition à « flush », qui l'envoie).

Syntaxe

ob_end_clean(): bool

Elle ne prend aucun argument et retourne un booléen.

Valeur de retour et gestion des erreurs

Puisqu'elle émet un avertissement quand aucun tampon n'est actif, protégez l'appel avec ob_get_level() lorsque vous n'êtes pas certain qu'un tampon est ouvert :

<?php
if (ob_get_level() > 0) {
    ob_end_clean();
}
?>

Exemple de base

<?php
ob_start();                 // Start buffering
echo "This will be thrown away";
ob_end_clean();             // Discard the buffer, stop buffering

echo "Only this line reaches the browser";
?>

Sortie :

Only this line reaches the browser

Le premier echo n'apparaît jamais : ob_end_clean() a supprimé le tampon qui contenait "This will be thrown away".

Quand l'utiliser ?

• Supprimer une sortie indésirable d'une fonction, d'une bibliothèque ou d'un gabarit que vous ne contrôlez pas, afin qu'elle ne puisse pas corrompre la réponse.
• Rejeter une page partiellement rendue quand une erreur ou une redirection survient en cours de traitement, afin que l'utilisateur reçoive une réponse propre plutôt qu'une réponse cassée.
• Capturer puis abandonner une sortie pendant les tests ou les mesures (par exemple, mesurer le temps de rendu sans réellement l'afficher).

<?php
ob_start();
try {
    render_complex_page();          // emits lots of output
    throw new RuntimeException('boom');
} catch (Throwable $e) {
    ob_end_clean();                 // drop the partial page
    http_response_code(500);
    echo "Sorry, something went wrong.";
}
?>

ob_end_clean() vs. fonctions associées

La famille ob_* se divise selon deux axes — clean vs. flush (rejeter vs. envoyer) et end vs. get (fermer le tampon vs. le garder ouvert / retourner une chaîne) :

Si vous avez besoin du texte rejeté sous forme de string, utilisez ob_get_clean() plutôt que ob_end_clean(). Pour envoyer le tampon au lieu de le supprimer, utilisez ob_end_flush(). Chacune de ces fonctions nécessite un tampon préalablement ouvert avec ob_start().

Tampons imbriqués

Les tampons de sortie forment une pile. ob_end_clean() n'affecte que le tampon le plus interne ; les tampons externes restent intacts. Chaque niveau doit être fermé par son propre appel :

<?php
ob_start();           // level 1
echo "outer ";
ob_start();           // level 2
echo "inner";
ob_end_clean();       // drops "inner", level 1 still open
echo " world";
ob_end_flush();       // sends "outer  world"
?>

Sortie :

outer  world

Conclusion

ob_end_clean() supprime le contenu du tampon de sortie actif et ferme ce niveau de mise en tampon, retournant true en cas de succès. Utilisez-la pour rejeter une sortie que vous ne souhaitez jamais envoyer — et utilisez ob_get_clean(), ob_end_flush() ou ob_clean() lorsque vous avez besoin du contenu, souhaitez l'envoyer, ou souhaitez continuer la mise en tampon. Consultez la vue d'ensemble du contrôle de sortie PHP pour une vue complète.

Pratique