Funzione PHP ob_end_clean(): Tutto Quello che Devi Sapere

Quando PHP è eseguito con il buffering dell'output attivo, tutto ciò che lo script invia con echo viene raccolto in un buffer in memoria anziché essere inviato direttamente al browser. A volte si vuole scartare completamente quell'output catturato e interrompere del tutto il buffering — ad esempio dopo aver catturato qualcosa solo per ispezionarlo, oppure quando un errore fa sì che la risposta parzialmente costruita non debba mai raggiungere l'utente. Questo è esattamente ciò che fa ob_end_clean(). Questa pagina ne illustra la sintassi, il valore restituito, i casi d'uso più comuni e le differenze rispetto alle funzioni ob_* correlate.

Cos'è la Funzione ob_end_clean()?

ob_end_clean() compie due operazioni in un'unica chiamata sul buffer di output più in alto (quello aperto più di recente):

1. Elimina il suo contenuto attuale — l'output memorizzato nel buffer viene cancellato, non inviato.
2. Disattiva quel livello di buffering — il buffer viene chiuso e rimosso dallo stack.

La funzione esiste dal PHP 4. Il nome si decodifica come output buffer (ob) — end — clean: "end" significa chiudere il livello del buffer, "clean" significa scartare il contenuto (al contrario di "flush", che lo invia).

Sintassi

ob_end_clean(): bool

Non accetta argomenti e restituisce un valore booleano.

Valore Restituito e Gestione degli Errori

Poiché genera un avviso quando nessun buffer è attivo, è bene proteggere la chiamata con ob_get_level() quando non si è certi che uno sia aperto:

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

Esempio 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";
?>

Output:

Only this line reaches the browser

Il primo echo non appare mai: ob_end_clean() ha eliminato il buffer che conteneva "This will be thrown away".

Quando Usarla?

• Sopprimere output indesiderato proveniente da una funzione, libreria o template che non si controlla, in modo che non possa corrompere la risposta.
• Scartare una pagina parzialmente renderizzata quando si verifica un errore o un reindirizzamento a metà processo, così l'utente riceve una risposta pulita invece di una rotta.
• Catturare e poi scartare l'output durante test o misurazioni (ad esempio per calcolare il tempo di rendering senza stampare effettivamente il risultato).

<?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. Funzioni Correlate

La famiglia ob_* si divide su due assi — clean vs. flush (scarta vs. invia) e end vs. get (chiude il buffer vs. lo mantiene aperto / restituisce una stringa):

Se si ha bisogno del testo scartato come stringa, usare ob_get_clean() invece di ob_end_clean(). Per inviare il buffer anziché eliminarlo, usare ob_end_flush(). Ognuna di queste funzioni richiede che un buffer sia stato preventivamente aperto con ob_start().

Buffer Annidati

I buffer di output formano uno stack. ob_end_clean() agisce solo sul buffer più interno; i buffer esterni rimangono intatti. Ogni livello richiede una propria chiamata per essere chiuso:

<?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"
?>

Output:

outer  world

Conclusione

ob_end_clean() elimina il contenuto del buffer di output attivo e chiude quel livello di buffering, restituendo true in caso di successo. Usarla per scartare output che non si vuole mai inviare — e ricorrere a ob_get_clean(), ob_end_flush(), o ob_clean() quando invece si ha bisogno del contenuto, lo si vuole inviare, o si vuole mantenere il buffering attivo. Consulta la panoramica del controllo dell'output PHP per un quadro completo.

Pratica