PHP ob_clean() : Tout ce que vous devez savoir

La fonction PHP ob_clean() supprime tout ce qui a été écrit dans le tampon de sortie courant sans désactiver la mise en mémoire tampon. C'est la fonction à utiliser lorsque votre script a déjà produit une sortie, mais que vous avez décidé que cette sortie est incorrecte (un var_dump de débogage oublié, un template à moitié rendu, un message d'erreur) et que vous souhaitez la supprimer pour continuer à générer du contenu propre.

Cette page explique ce que fait ob_clean(), sa signature et sa valeur de retour, les pièges courants (notamment la différence avec ob_end_clean()), ainsi que des exemples d'utilisation pratiques.

Qu'est-ce que la mise en mémoire tampon de sortie

Normalement, PHP envoie la sortie au client dès que vous utilisez echo. La mise en mémoire tampon de sortie change ce comportement : après avoir appelé ob_start(), tout ce que vous affichez est capturé dans un tampon en mémoire au lieu d'être envoyé immédiatement. Rien ne quitte PHP tant que vous ne videz pas le tampon ou que le script ne se termine pas.

Ce délai est ce qui rend la mise en tampon utile — tant que la sortie se trouve dans le tampon, vous pouvez encore :

• envoyer ou modifier des en-têtes HTTP (header(), setcookie()) même après un affichage,
• inspecter, réécrire ou supprimer la sortie capturée,
• compresser l'intégralité de la réponse avant de l'envoyer.

ob_clean() correspond à l'opération « supprimer » dans cette liste.

Syntaxe

ob_clean(): bool

• Paramètres : aucun.
• Valeur de retour : true en cas de succès, false en cas d'échec. Elle échoue (et émet une notice/avertissement) lorsqu'il n'y a pas de tampon de sortie actif à nettoyer.

Un exemple de base

<?php
ob_start();                       // start buffering

echo "This text is buffered.\n";
ob_clean();                       // throw the buffered text away

echo "Only this line is shown.\n";

ob_end_flush();                   // send remaining buffer to output

Sortie :

Only this line is shown.

Le premier echo est allé dans le tampon, ob_clean() l'a vidé, et seul le second echo a survécu. Notez que la mise en tampon est toujours active après ob_clean() — c'est pourquoi le ob_end_flush() final est nécessaire pour émettre effectivement la deuxième ligne.

Un cas d'utilisation concret : abandonner un rendu incorrect

ob_clean() est particulièrement utile lorsque vous générez une sortie de manière optimiste et que vous rencontrez ensuite une condition qui l'invalide :

<?php
function renderUser(?array $user): string
{
    ob_start();

    echo "<div class='card'>";
    echo "  <h2>" . ($user['name'] ?? '') . "</h2>";

    if (empty($user)) {
        ob_clean();                       // scrap the half-built card
        echo "<p>User not found.</p>";    // start fresh
        return ob_get_clean();
    }

    echo "</div>";
    return ob_get_clean();
}

echo renderUser(null);            // <p>User not found.</p>
echo "\n";
echo renderUser(['name' => 'Ann']);

Sortie :

<p>User not found.</p>
<div class='card'>  <h2>Ann</h2></div>

Ici, ob_get_clean() retourne le contenu du tampon et termine la mise en tampon en une seule étape, tandis que ob_clean() est utilisé en cours de rendu pour abandonner le balisage partiellement construit.

ob_clean() par rapport aux fonctions similaires

La famille de contrôle de sortie comporte quatre noms d'apparence similaire. Les deux axes sont retournez-vous les données ? et conservez-vous le tampon ?

L'erreur courante est d'utiliser ob_end_clean() alors que l'on voulait ob_clean() : le premier ferme le niveau du tampon, de sorte qu'un echo ultérieur n'est plus mis en tampon et qu'un appel ob_* suivant peut avertir qu'aucun tampon n'est actif.

Pièges à éviter

• La mise en tampon doit être active. Appeler ob_clean() sans ob_start() en vigueur retourne false et génère une notice. Protégez-vous avec ob_get_level() en cas de doute : if (ob_get_level() > 0) { ob_clean(); }.
• Elle ne nettoie que le tampon le plus récent. Les tampons s'imbriquent. ob_clean() affecte le tampon le plus interne (le plus récemment démarré), pas tous.
• Elle ne réinitialise pas les en-têtes. ob_clean() vide uniquement le texte de sortie ; les en-têtes déjà mis en file d'attente avec header() ne sont pas affectés.

Conclusion

ob_clean() supprime le contenu du tampon de sortie courant tout en laissant la mise en tampon activée, ce qui en fait l'outil idéal pour abandonner une sortie que vous avez décidé de ne pas envoyer et pour repartir d'une ardoise propre. N'oubliez pas la distinction avec ob_end_clean() (qui ferme également le tampon) et avec ob_get_clean() (qui vous restitue le contenu). Pour une vue d'ensemble de toute la famille, consultez PHP Output Control.

Pratique