connection_aborted()

Cosa fa connection_aborted()

La funzione connection_aborted() indica se il client (di solito un browser) si è disconnesso prima che lo script terminasse l'invio della risposta. Un client "interrompe" la connessione quando il visitatore chiude la scheda, preme il pulsante stop, naviga altrove o perde la connessione di rete.

Non accetta argomenti e restituisce un intero:

• 1 se la connessione è stata interrotta dal client,
• 0 se la connessione è ancora attiva.

connection_aborted(): int

In pratica il valore restituito viene trattato come un boolean, quindi if (connection_aborted()) si legge naturalmente come "se il client se ne è andato."

Quando utilizzarla

Per la maggior parte delle pagine questa funzione non è mai necessaria — PHP si ferma semplicemente quando il client si disconnette. Diventa utile per script a lunga esecuzione che devono eseguire operazioni di pulizia o aggiornamento anche quando nessuno attende il risultato, ad esempio:

• Un report o un'esportazione che richiede minuti per essere generata e deve salvare un risultato parziale o eseguire un rollback in caso di disconnessione.
• Uno script che scrive l'avanzamento su un log e deve registrare "l'utente ha abbandonato al passaggio 7."
• Un'attività in background avviata da una richiesta web che deve continuare a funzionare dopo che l'utente ha lasciato la pagina.

C'è un'importante avvertenza: PHP non può rilevare una connessione interrotta finché non tenta di inviare output al client. Quindi connection_aborted() passa a 1 solo dopo aver tentato una scrittura (echo/print) e aver svuotato il buffer. In genere viene abbinata a flush() all'interno di un ciclo, in modo che PHP invii effettivamente i dati e rilevi la disconnessione.

Per impostazione predefinita PHP termina anche lo script nel momento in cui rileva che il client se ne è andato. Per continuare l'esecuzione dopo una disconnessione — che è proprio lo scopo del controllo con connection_aborted() — è necessario chiamare prima ignore_user_abort(true).

Esempio di base

Questo script chiede a PHP di continuare l'esecuzione dopo una disconnessione, poi entra in un ciclo e controlla la connessione a ogni iterazione. Quando il client interrompe la connessione, scrive una nota in un log e si ferma.

<?php

// Keep executing even if the client disconnects.
ignore_user_abort(true);

for ($i = 0; $i < 60; $i++) {
    // Send something and flush so PHP can detect a closed connection.
    echo "Working on step $i ...\n";
    flush();

    if (connection_aborted()) {
        file_put_contents('job.log', "Client left at step $i\n", FILE_APPEND);
        break;
    }

    sleep(1); // simulate slow work
}

connection_aborted() restituisce 0 finché il browser è ancora in ascolto e 1 dopo che il visitatore chiude la scheda; il break termina quindi il ciclo in modo pulito.

Distinguere il motivo dell'interruzione dello script

Uno script a lunga esecuzione può terminare per due motivi: il client ha interrotto la connessione, oppure è stato raggiunto il limite di tempo configurato. connection_aborted() risponde al primo caso; connection_status() risponde a entrambi contemporaneamente restituendo una maschera di bit. Il seguente snippet autonomo mostra i valori costanti usati da PHP, che è possibile eseguire con la CLI PHP:

<?php

// The bit flags returned by connection_status()
echo "ABORTED  = " . CONNECTION_ABORTED . "\n"; // 1
echo "TIMEOUT  = " . CONNECTION_TIMEOUT . "\n";  // 2
echo "NORMAL   = " . CONNECTION_NORMAL . "\n";   // 0

L'esecuzione produce:

ABORTED  = 1
TIMEOUT  = 2
NORMAL   = 0

Quindi connection_aborted() è di fatto un'abbreviazione per verificare il bit CONNECTION_ABORTED di connection_status().

Problemi comuni

• Richiede output e flush. Senza echo/flush(), l'interruzione non viene mai rilevata e connection_aborted() rimane 0.
• Il buffering dell'output nasconde le interruzioni. Se ob_start() o il buffering implicito trattengono l'output, PHP non scrive mai sul socket. Svuota i buffer (ad esempio con ob_flush() seguito da flush()).
• Funziona solo in una richiesta web. Eseguita dalla CLI, la funzione restituisce sempre 0 perché non esiste un client che possa disconnettersi.
• Di solito è necessario chiamare prima ignore_user_abort(true), altrimenti lo script viene terminato prima che il controllo venga eseguito.

Conclusione

connection_aborted() permette a uno script PHP di reagire quando un visitatore si disconnette durante una richiesta — restituisce 1 dopo una connessione interrotta e 0 mentre è ancora aperta. È più utile negli script a lunga esecuzione, dove viene abbinata a ignore_user_abort() e flush() per completare le operazioni di pulizia anche quando nessuno attende la risposta.

Pratica