connection_aborted()

Was connection_aborted() macht

Die Funktion connection_aborted() gibt an, ob der Client (in der Regel ein Browser) die Verbindung getrennt hat, bevor Ihr Skript die Antwort vollständig gesendet hat. Ein Client „bricht ab", wenn der Besucher den Tab schließt, die Stopp-Schaltfläche drückt, zu einer anderen Seite navigiert oder die Netzwerkverbindung verliert.

Die Funktion nimmt keine Argumente entgegen und gibt eine Ganzzahl zurück:

• 1, wenn die Verbindung vom Client abgebrochen wurde,
• 0, wenn die Verbindung noch aktiv ist.

connection_aborted(): int

In der Praxis wird der Rückgabewert wie ein boolean behandelt, sodass if (connection_aborted()) sich natürlich liest als „wenn der Client weg ist."

Wann Sie diese Funktion benötigen

Für die meisten Seiten brauchen Sie diese Funktion nie — PHP stoppt einfach, wenn der Client die Verbindung trennt. Nützlich wird sie bei lang laufenden Skripten, die aufräumen oder Buchführung betreiben müssen, auch wenn niemand mehr auf das Ergebnis wartet, zum Beispiel:

• Ein Bericht oder Export, der Minuten zur Erstellung benötigt und ein Teilergebnis speichern oder bei einem Disconnect zurückrollen muss.
• Ein Skript, das den Fortschritt in eine Logdatei schreibt und festhalten soll: „Der Benutzer hat bei Schritt 7 aufgegeben."
• Eine hintergrundähnliche Aufgabe, die durch eine Webanfrage ausgelöst wurde und nach dem Abgang des Benutzers weiterarbeiten soll.

Es gibt einen wichtigen Vorbehalt: PHP kann eine unterbrochene Verbindung erst erkennen, wenn es das nächste Mal versucht, Ausgabe an den Client zu senden. connection_aborted() wechselt daher nur dann auf 1, nachdem Sie einen Schreibvorgang (echo/print) versucht haben und der Puffer geleert wurde. Typischerweise kombinieren Sie die Funktion mit flush() innerhalb einer Schleife, damit PHP die Daten tatsächlich überträgt und den Disconnect bemerkt.

Standardmäßig beendet PHP das Skript auch in dem Moment, in dem es erkennt, dass der Client weg ist. Um nach einem Disconnect weiterzulaufen — was der eigentliche Sinn der eigenen Prüfung mit connection_aborted() ist — müssen Sie zunächst ignore_user_abort(true) aufrufen.

Einfaches Beispiel

Dieses Skript weist PHP an, nach einem Disconnect weiterzulaufen, und prüft dann in jeder Iteration der Schleife den Verbindungsstatus. Wenn der Client abbricht, schreibt es einen Eintrag in eine Logdatei und bricht ab.

<?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() gibt 0 zurück, solange der Browser noch lauscht, und 1, nachdem der Besucher den Tab geschlossen hat; das break beendet die Schleife dann sauber.

Unterscheiden, warum das Skript gestoppt hat

Ein lang laufendes Skript kann aus zwei Gründen enden: Der Client hat abgebrochen, oder das konfigurierte Zeitlimit wurde erreicht. connection_aborted() beantwortet das Erstere; connection_status() beantwortet beides gleichzeitig, indem es eine Bitmaske zurückgibt. Das folgende eigenständige Snippet zeigt die Konstantenwerte, die PHP verwendet, und kann mit der PHP-CLI ausgeführt werden:

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

Bei der Ausführung wird Folgendes ausgegeben:

ABORTED  = 1
TIMEOUT  = 2
NORMAL   = 0

connection_aborted() ist also effektiv eine Kurzform für das Testen des CONNECTION_ABORTED-Bits von connection_status().

Häufige Fallstricke

• Es benötigt Ausgabe + flush. Ohne ein echo/flush() wird der Abbruch nie erkannt, und connection_aborted() bleibt bei 0.
• Output-Buffering verbirgt Abbrüche. Wenn ob_start() oder implizites Buffering die Ausgabe zurückhält, schreibt PHP nie in den Socket. Leeren Sie die Puffer (z. B. mit ob_flush() gefolgt von flush()).
• Es funktioniert nur bei einer Webanfrage. Bei der Ausführung über die CLI gibt die Funktion immer 0 zurück, da es keinen Client gibt, der die Verbindung trennen könnte.
• In der Regel sollten Sie zuerst ignore_user_abort(true) aufrufen, sonst wird das Skript beendet, bevor Ihre Prüfung überhaupt ausgeführt wird.

Fazit

connection_aborted() ermöglicht es einem PHP-Skript, zu reagieren, wenn ein Besucher die Verbindung während einer Anfrage trennt — es gibt 1 nach einer abgebrochenen Verbindung zurück und 0, solange die Verbindung noch offen ist. Es ist am wertvollsten in lang laufenden Skripten, wo Sie es mit ignore_user_abort() und flush() kombinieren, um Aufräumarbeiten auch dann abzuschließen, wenn niemand mehr auf die Antwort wartet.

Übungen