PHP socket_get_status() Function: Everything You Need to Know

When you read from or write to a network connection in PHP, you often need to know whether the connection is still alive, whether a read timed out, or how many bytes are waiting in the buffer. The socket_get_status() function answers exactly these questions: it returns a snapshot of the current state of a stream.

This chapter explains what socket_get_status() returns, when each field matters, and how to use it safely with timeouts and non-blocking streams.

What is the socket_get_status() Function?

socket_get_status() retrieves the current status of a stream resource as an associative array. It is actually an alias of stream_get_meta_data(), so the two return the same data — socket_get_status() is simply the historical name kept for networking code.

Despite the name, the function is designed for stream resources — the kind returned by fsockopen(), pfsockopen(), or stream_socket_client() — and not for the low-level socket resources created by socket_create(). Passing the wrong resource type can trigger deprecation warnings in PHP 8+ and will not give you the data you expect.

How to Use the socket_get_status() Function

Using the socket_get_status() function is straightforward. Here is the syntax of the function:

The PHP syntax of the socket_get_status() function

socket_get_status(resource $stream): array

The function takes one parameter:

• $stream: The stream resource whose status you want to retrieve.

It returns an associative array. The most useful keys are:

Checking whether a connection is still open

Here is a minimal example that opens a TCP stream, reads a line, and uses socket_get_status() to decide whether the server has closed the connection:

How to use the socket_get_status() function?

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

We use fsockopen() to create a stream and check it was created successfully before doing anything else. After sending a request and reading one line with fgets(), the eof field tells us whether the remote end has finished. Always close the stream with fclose() when you are done.

Detecting a read timeout

The timed_out field is what makes socket_get_status() genuinely useful. When you set a read timeout with stream_set_timeout() (or socket_set_timeout()), a slow read does not throw — fgets() simply returns false. You then call socket_get_status() to find out why it returned 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);
?>

Because no request was sent, the server has nothing to reply with, the 2-second timeout fires, and the script prints Read timed out. Without socket_get_status() you could not distinguish a timeout from a genuine end-of-stream — both make fgets() return false.

When to use socket_get_status()

• After a failed read. fgets()/fread() returning false is ambiguous; check timed_out and eof to learn what happened.
• Before reusing a connection. Inspect eof to confirm a keep-alive socket is still alive before sending another request.
• With non-blocking streams. When you call stream_set_blocking() to make a socket non-blocking, unread_bytes and blocked help you reason about buffered data.

Gotchas

• It works on stream resources only — not socket_create() resources. For those, use socket_last_error() / socket_get_option() instead.
• socket_get_status() reflects the buffer and timeout state at the moment you call it; it does not actively probe the network, so an eof of false is not a guarantee the peer is still reachable.
• Reset the timeout flag by performing another successful read — the array is recomputed on every call.

Conclusion

The socket_get_status() function is a lightweight way to inspect the state of a stream socket in PHP. Its most valuable field is timed_out, which lets you tell a read timeout apart from a closed connection — something the return value of fgets() alone cannot do. Combined with eof, unread_bytes, and the timeout and blocking controls from stream_set_timeout() and stream_set_blocking(), it gives you the information you need to handle network connections reliably.

Practice