connection_aborted()

Ce que fait connection_aborted()

La fonction connection_aborted() indique si le client (généralement un navigateur) s'est déconnecté avant que votre script ait fini d'envoyer sa réponse. Un client « interrompt » la connexion lorsque le visiteur ferme l'onglet, appuie sur le bouton d'arrêt, navigue ailleurs ou perd sa connexion réseau.

Elle ne prend aucun argument et retourne un entier :

• 1 si la connexion a été interrompue par le client,
• 0 si la connexion est toujours active.

connection_aborted(): int

En pratique, la valeur de retour est traitée comme un boolean, ainsi if (connection_aborted()) se lit naturellement comme « si le client est parti ».

Pourquoi l'utiliser

Pour la plupart des pages, vous n'aurez jamais besoin de cette fonction — PHP s'arrête simplement quand le client se déconnecte. Elle devient utile pour les scripts de longue durée qui doivent effectuer un nettoyage ou une comptabilité même lorsque personne n'attend le résultat, par exemple :

• Un rapport ou une exportation qui prend plusieurs minutes à générer et doit valider un résultat partiel ou l'annuler en cas de déconnexion.
• Un script qui enregistre la progression dans un journal et doit noter « l'utilisateur a abandonné à l'étape 7 ».
• Une tâche de type arrière-plan déclenchée par une requête web qui doit continuer à s'exécuter après que l'utilisateur soit parti.

Il y a un point important à connaître : PHP ne peut pas détecter une connexion interrompue avant sa prochaine tentative d'envoi de données au client. Donc connection_aborted() ne passe à 1 qu'après une tentative d'écriture (echo/print) et que le tampon est vidé. Vous l'associez généralement à flush() dans une boucle afin que PHP envoie réellement les données et détecte la déconnexion.

Par défaut, PHP tue également le script dès qu'il détecte que le client est parti. Pour continuer à s'exécuter après une déconnexion — ce qui est tout l'intérêt de vérifier connection_aborted() vous-même — vous devez d'abord appeler ignore_user_abort(true).

Exemple de base

Ce script demande à PHP de continuer à s'exécuter après une déconnexion, puis boucle et vérifie la connexion à chaque itération. Lorsque le client interrompt la connexion, il écrit une note dans un journal et s'arrête.

<?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() retourne 0 tant que le navigateur écoute encore et 1 après que le visiteur a fermé l'onglet ; le break met alors fin à la boucle proprement.

Distinguer la raison d'arrêt du script

Un script de longue durée peut se terminer pour deux raisons : le client a interrompu la connexion, ou il a atteint la limite de temps configurée. connection_aborted() répond à la première ; connection_status() répond aux deux à la fois en retournant un masque de bits. L'extrait autonome suivant montre les valeurs des constantes utilisées par PHP, que vous pouvez exécuter avec le 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

Lors de l'exécution, cela affiche :

ABORTED  = 1
TIMEOUT  = 2
NORMAL   = 0

Ainsi, connection_aborted() est effectivement un raccourci pour tester le bit CONNECTION_ABORTED de connection_status().

Pièges courants

• Elle nécessite une sortie + un vidage de tampon. Sans echo/flush(), l'interruption n'est jamais détectée et connection_aborted() reste à 0.
• La mise en tampon de sortie masque les interruptions. Si ob_start() ou une mise en tampon implicite retient votre sortie, PHP n'écrit jamais dans le socket. Videz les tampons (par exemple avec ob_flush() puis flush()).
• Elle ne fonctionne que dans une requête web. Exécutée depuis le CLI, la fonction retourne toujours 0 car il n'y a pas de client à déconnecter.
• Vous voudrez généralement appeler ignore_user_abort(true) en premier, sinon le script est terminé avant que votre vérification ne s'exécute.

Conclusion

connection_aborted() permet à un script PHP de réagir lorsqu'un visiteur se déconnecte en cours de requête — en retournant 1 après une connexion interrompue et 0 tant qu'elle est encore ouverte. Elle est particulièrement utile dans les scripts de longue durée, où vous l'associez à ignore_user_abort() et flush() pour terminer le travail de nettoyage même quand personne n'attend la réponse.

Pratique