Funzione PHP ob_clean(): tutto quello che devi sapere

La funzione PHP ob_clean() scarta tutto ciò che è stato scritto nel buffer di output corrente senza disattivare il buffering. È la funzione a cui si ricorre quando lo script ha già prodotto dell'output, ma si è deciso che quell'output è errato (un var_dump di debug rimasto, un template parzialmente renderizzato, un messaggio di errore) e si vuole eliminarlo per continuare a generare contenuto nuovo.

Questa pagina spiega cosa fa ob_clean(), la sua firma e il valore restituito, i problemi più comuni (in particolare la differenza rispetto a ob_end_clean()), e i pattern pratici per utilizzarla.

Cos'è il buffering dell'output

Normalmente PHP invia l'output al client nel momento stesso in cui si usa echo. Il buffering dell'output cambia questo comportamento: dopo aver chiamato ob_start(), tutto ciò che viene stampato viene catturato in un buffer in memoria anziché essere inviato immediatamente. Nulla lascia PHP finché non si svuota il buffer o lo script non termina.

Questo ritardo è ciò che rende utile il buffering — mentre l'output si trova nel buffer è ancora possibile:

• inviare o modificare gli header HTTP (header(), setcookie()) anche dopo aver stampato,
• ispezionare, riscrivere o scartare l'output acquisito,
• comprimere l'intera risposta prima di inviarla.

ob_clean() è l'operazione di "scarto" in quell'elenco.

Sintassi

ob_clean(): bool

• Parametri: nessuno.
• Valore restituito: true in caso di successo, false in caso di errore. Fallisce (ed emette un notice/warning) quando non esiste nessun buffer di output attivo da pulire.

Un esempio di 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

Output:

Only this line is shown.

La prima echo è finita nel buffer, ob_clean() lo ha svuotato e solo la seconda echo è sopravvissuta. Da notare che il buffering è ancora attivo dopo ob_clean() — ecco perché è necessario il finale ob_end_flush() per emettere effettivamente la seconda riga.

Un caso d'uso reale: scartare un render non riuscito

ob_clean() è particolarmente utile quando si genera output in modo ottimistico e poi si incontra una condizione che lo invalida:

<?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']);

Output:

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

Qui ob_get_clean() restituisce il contenuto del buffer e termina il buffering in un unico passaggio, mentre ob_clean() viene usata a metà render per abbandonare il markup parzialmente costruito.

ob_clean() vs le funzioni correlate

La famiglia delle funzioni di controllo dell'output ha quattro nomi dall'aspetto simile. I due assi sono si conservano i dati? e si mantiene aperto il buffer?

Quindi l'errore più comune è usare ob_end_clean() quando si intendeva usare ob_clean(): la prima chiude il livello del buffer, quindi una successiva echo non viene più bufferizzata e qualsiasi chiamata ob_* successiva potrebbe avvertire che nessun buffer è attivo.

Problemi comuni

• Il buffering deve essere attivo. Chiamare ob_clean() senza un ob_start() attivo restituisce false e genera un notice. Usa ob_get_level() come guardia se non sei sicuro: if (ob_get_level() > 0) { ob_clean(); }.
• Pulisce solo il buffer superiore. I buffer si annidano. ob_clean() agisce sul buffer più interno (quello avviato più di recente), non su tutti.
• Non azzera gli header. ob_clean() svuota solo il testo di output; gli header già accodati con header() non vengono modificati.

Conclusione

ob_clean() scarta il contenuto del buffer di output corrente lasciando il buffering attivo, rendendola lo strumento giusto per abbandonare output che si è deciso di non inviare e riprendere da una base pulita. Ricorda la distinzione da ob_end_clean() (che chiude anche il buffer) e da ob_get_clean() (che ti restituisce il contenuto). Per una panoramica dell'intera famiglia, consulta PHP Output Control.

Pratica