connection_aborted()

O que connection_aborted() faz

A função connection_aborted() informa se o cliente (geralmente um navegador) desconectou antes de seu script terminar de enviar a resposta. Um cliente "aborta" quando o visitante fecha a aba, clica no botão de parar, navega para outra página ou perde a conexão de rede.

Não recebe argumentos e retorna um inteiro:

• 1 se a conexão foi interrompida pelo cliente,
• 0 se a conexão ainda está ativa.

connection_aborted(): int

Na prática, o valor de retorno é tratado como um boolean, portanto if (connection_aborted()) se lê naturalmente como "se o cliente foi embora."

Por que você usaria isso

Na maioria das páginas você nunca precisará dessa função — o PHP simplesmente para quando o cliente desconecta. Ela se torna útil em scripts de longa duração que precisam fazer limpeza ou registro mesmo quando ninguém está aguardando o resultado, por exemplo:

• Um relatório ou exportação que leva minutos para ser gerado e deve confirmar um resultado parcial ou fazer rollback ao desconectar.
• Um script que registra o progresso em um log e precisa gravar "o usuário desistiu no passo 7."
• Uma tarefa em segundo plano acionada por uma requisição web que deve continuar funcionando após o usuário sair.

Há um ponto importante: o PHP não consegue detectar uma conexão interrompida até que tente enviar saída ao cliente. Portanto, connection_aborted() só muda para 1 após uma tentativa de escrita (echo/print) e o buffer ser descarregado. Você normalmente a usa com flush() dentro de um loop para que o PHP efetivamente envie dados e perceba a desconexão.

Por padrão, o PHP também encerra o script no momento em que detecta que o cliente saiu. Para continuar executando após uma desconexão — que é o objetivo principal de verificar connection_aborted() você mesmo — você deve primeiro chamar ignore_user_abort(true).

Exemplo básico

Este script pede ao PHP para continuar executando após uma desconexão, então faz um loop e verifica a conexão a cada iteração. Quando o cliente aborta, ele grava uma nota em um log e para.

<?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() retorna 0 enquanto o navegador ainda está ouvindo e 1 após o visitante fechar a aba; o break então encerra o loop de forma limpa.

Distinguindo o motivo pelo qual o script parou

Um script de longa duração pode terminar por dois motivos: o cliente abortou, ou o limite de tempo configurado foi atingido. connection_aborted() responde ao primeiro; connection_status() responde a ambos de uma vez, retornando um bitmask. O trecho isolado a seguir mostra os valores constantes que o PHP utiliza, que podem ser executados com o CLI do 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

Ao ser executado, imprime:

ABORTED  = 1
TIMEOUT  = 2
NORMAL   = 0

Portanto, connection_aborted() é efetivamente um atalho para testar o bit CONNECTION_ABORTED de connection_status().

Armadilhas comuns

• Requer saída + flush. Sem um echo/flush(), o abort nunca é detectado e connection_aborted() permanece 0.
• O buffering de saída oculta os aborts. Se ob_start() ou buffering implícito retiver sua saída, o PHP nunca grava no socket. Descarregue os buffers (por exemplo com ob_flush() e depois flush()).
• Funciona apenas em uma requisição web. Executada pela CLI, a função sempre retorna 0 porque não há cliente para desconectar.
• Geralmente você precisa chamar ignore_user_abort(true) primeiro, caso contrário o script é encerrado antes de sua verificação ser executada.

Conclusão

connection_aborted() permite que um script PHP reaja quando um visitante desconecta no meio de uma requisição — retornando 1 após uma conexão interrompida e 0 enquanto ainda está aberta. É mais valiosa em scripts de longa duração, onde é combinada com ignore_user_abort() e flush() para concluir o trabalho de limpeza mesmo quando ninguém aguarda a resposta.

Prática