connection_aborted()

Qué hace connection_aborted()

La función connection_aborted() te indica si el cliente (generalmente un navegador) se ha desconectado antes de que tu script terminara de enviar su respuesta. Un cliente "interrumpe" la conexión cuando el visitante cierra la pestaña, presiona el botón de detener, navega a otra página o pierde su conexión de red.

No recibe argumentos y devuelve un entero:

• 1 si el cliente interrumpió la conexión,
• 0 si la conexión sigue activa.

connection_aborted(): int

En la práctica, el valor de retorno se trata como un boolean, por lo que if (connection_aborted()) se lee de forma natural como "si el cliente ya no está disponible."

Por qué la usarías

Para la mayoría de las páginas nunca necesitarás esta función — PHP simplemente se detiene cuando el cliente se desconecta. Se vuelve útil para scripts de larga duración que deben realizar tareas de limpieza o registro incluso cuando nadie espera el resultado, por ejemplo:

• Un informe o exportación que tarda minutos en generarse y debe confirmar un resultado parcial o revertir los cambios al desconectarse.
• Un script que envía progreso a un registro y necesita anotar "el usuario abandonó en el paso 7."
• Una tarea en segundo plano activada por una solicitud web que debe continuar ejecutándose después de que el usuario se vaya.

Hay una advertencia importante: PHP no puede detectar una conexión interrumpida hasta que intente enviar salida al cliente. Por tanto, connection_aborted() solo cambia a 1 después de intentar una escritura (echo/print) y vaciar el búfer. Normalmente se combina con flush() dentro de un bucle para que PHP realmente envíe datos y detecte la desconexión.

Por defecto, PHP también termina el script en el momento en que detecta que el cliente se fue. Para seguir ejecutando tras una desconexión — que es el objetivo principal de verificar connection_aborted() tú mismo — primero debes llamar a ignore_user_abort(true).

Ejemplo básico

Este script le pide a PHP que continúe ejecutándose tras una desconexión, luego itera y verifica la conexión en cada ciclo. Cuando el cliente interrumpe la conexión, escribe una nota en un registro y se detiene.

<?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() devuelve 0 mientras el navegador sigue escuchando y 1 después de que el visitante cierra la pestaña; el break entonces finaliza el bucle de forma limpia.

Distinguir por qué se detuvo el script

Un script de larga duración puede finalizar por dos razones: el cliente interrumpió la conexión o alcanzó el límite de tiempo configurado. connection_aborted() responde a la primera; connection_status() responde a ambas a la vez devolviendo una máscara de bits. El siguiente fragmento independiente muestra los valores de las constantes que usa PHP, que puedes ejecutar con el CLI de 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

Al ejecutarlo, imprime:

ABORTED  = 1
TIMEOUT  = 2
NORMAL   = 0

Por tanto, connection_aborted() es efectivamente un atajo para probar el bit CONNECTION_ABORTED de connection_status().

Errores comunes

• Necesita salida y flush. Sin un echo/flush(), la interrupción nunca se detecta y connection_aborted() permanece en 0.
• El búfer de salida oculta las interrupciones. Si ob_start() o el búfer implícito retiene tu salida, PHP nunca escribe en el socket. Vacía los búferes (por ejemplo con ob_flush() seguido de flush()).
• Solo funciona en una solicitud web. Al ejecutarse desde el CLI, la función siempre devuelve 0 porque no hay ningún cliente que se pueda desconectar.
• Generalmente querrás ignore_user_abort(true) primero, o el script se terminará antes de que tu comprobación llegue a ejecutarse.

Conclusión

connection_aborted() permite que un script PHP reaccione cuando un visitante se desconecta a mitad de una solicitud — devolviendo 1 tras una conexión interrumpida y 0 mientras sigue abierta. Es más valioso en scripts de larga duración donde se combina con ignore_user_abort() y flush() para completar el trabajo de limpieza incluso cuando nadie espera la respuesta.

Práctica