Função PHP socket_get_status(): Tudo o que Você Precisa Saber

Ao ler ou escrever em uma conexão de rede no PHP, muitas vezes você precisa saber se a conexão ainda está ativa, se uma leitura expirou por timeout ou quantos bytes estão aguardando no buffer. A função socket_get_status() responde exatamente a essas perguntas: ela retorna um instantâneo do estado atual de um stream.

Este capítulo explica o que socket_get_status() retorna, quando cada campo é relevante e como usá-la com segurança junto a timeouts e streams não bloqueantes.

O que é a Função socket_get_status()?

socket_get_status() recupera o status atual de um recurso de stream como um array associativo. Na prática, ela é um alias de stream_get_meta_data(), portanto as duas retornam os mesmos dados — socket_get_status() é simplesmente o nome histórico mantido para código de rede.

Apesar do nome, a função foi projetada para recursos de stream — do tipo retornado por fsockopen(), pfsockopen() ou stream_socket_client() — e não para os recursos de socket de baixo nível criados por socket_create(). Passar o tipo de recurso errado pode acionar avisos de depreciação no PHP 8+ e não fornecerá os dados esperados.

Como Usar a Função socket_get_status()

O uso da função socket_get_status() é simples. Veja a sintaxe da função:

A sintaxe PHP da função socket_get_status()

socket_get_status(resource $stream): array

A função aceita um parâmetro:

• $stream: O recurso de stream cujo status você deseja recuperar.

Ela retorna um array associativo. As chaves mais úteis são:

Verificando se uma conexão ainda está aberta

Veja um exemplo mínimo que abre um stream TCP, lê uma linha e usa socket_get_status() para determinar se o servidor fechou a conexão:

Como usar a função socket_get_status()?

<?php

$stream = fsockopen("tcp://www.example.com", 80, $errno, $errstr, 30);
if (!$stream) {
    die("Error: $errstr ($errno)");
}

fwrite($stream, "GET / HTTP/1.0\r\nHost: www.example.com\r\n\r\n");
$line = fgets($stream);

$status = socket_get_status($stream);
echo $status["eof"] ? "Connection closed by server\n" : "Connection still open\n";

fclose($stream);
?>

Usamos fsockopen() para criar um stream e verificamos se ele foi criado com sucesso antes de continuar. Após enviar uma requisição e ler uma linha com fgets(), o campo eof nos informa se a extremidade remota terminou. Sempre feche o stream com fclose() quando terminar.

Detectando um timeout de leitura

O campo timed_out é o que torna socket_get_status() genuinamente útil. Quando você define um timeout de leitura com stream_set_timeout() (ou socket_set_timeout()), uma leitura lenta não lança exceção — fgets() simplesmente retorna false. Você então chama socket_get_status() para descobrir por que ela retornou false:

<?php

$stream = fsockopen("tcp://www.example.com", 80, $errno, $errstr, 30);
if (!$stream) {
    die("Error: $errstr ($errno)");
}

// Wait at most 2 seconds for data before giving up.
stream_set_timeout($stream, 2);

$line = fgets($stream); // We never sent a request, so nothing arrives.

$status = socket_get_status($stream);
if ($status["timed_out"]) {
    echo "Read timed out\n";
} else {
    echo "Got data\n";
}

fclose($stream);
?>

Como nenhuma requisição foi enviada, o servidor não tem nada para responder, o timeout de 2 segundos dispara e o script imprime Read timed out. Sem socket_get_status(), você não conseguiria distinguir um timeout de um fim de stream real — ambos fazem fgets() retornar false.

Quando usar socket_get_status()

• Após uma leitura falha. fgets()/fread() retornando false é ambíguo; verifique timed_out e eof para entender o que ocorreu.
• Antes de reutilizar uma conexão. Inspecione eof para confirmar que um socket keep-alive ainda está ativo antes de enviar outra requisição.
• Com streams não bloqueantes. Quando você chama stream_set_blocking() para tornar um socket não bloqueante, unread_bytes e blocked ajudam a entender os dados em buffer.

Armadilhas

• Funciona apenas em recursos de stream — não em recursos socket_create(). Para esses, use socket_last_error() / socket_get_option() em vez disso.
• socket_get_status() reflete o estado do buffer e do timeout no momento em que é chamada; ela não sonda ativamente a rede, portanto um eof igual a false não garante que o par ainda está acessível.
• Redefina o indicador de timeout realizando outra leitura bem-sucedida — o array é recomputado a cada chamada.

Conclusão

A função socket_get_status() é uma forma leve de inspecionar o estado de um socket de stream no PHP. Seu campo mais valioso é timed_out, que permite distinguir um timeout de leitura de uma conexão fechada — algo que o valor de retorno de fgets() sozinho não consegue fazer. Combinada com eof, unread_bytes e os controles de timeout e bloqueio de stream_set_timeout() e stream_set_blocking(), ela fornece as informações necessárias para lidar com conexões de rede de forma confiável.

Prática