PHP stream_socket_client() Function: Usage and Examples

In PHP, stream_socket_client() is useful when your application needs a specific operation rather than manually reproducing it. Opens a client connection to a stream transport such as TCP or TLS, with a timeout and context options.

Stream functions work with PHP stream resources, wrappers, contexts or custom filters. Not every wrapper supports every operation.

What Is stream_socket_client() in PHP?

Opens a client connection to a stream transport such as TCP or TLS, with a timeout and context options.

Signature:

stream_socket_client(string $address, $error_code = NULL, $error_message = NULL, ?float $timeout = NULL, int $flags = STREAM_CLIENT_CONNECT, $context = NULL): mixed

Parameters:

$address — Socket transport URI or endpoint address.
$error_code — Reference variable receiving the transport error code on failure.
$error_message — Reference variable receiving the transport error description on failure.
$timeout — Maximum wait duration, usually expressed in seconds.
$flags — Bitmask controlling behavior. Combine only flags documented for this function.
$context — Stream context resource containing wrapper options or callbacks.

Return value: The return type depends on the result of this operation; inspect errors and exceptions as documented for the API..

Example 1: Basic Usage

This first example shows the method or function in a minimal context. For environment-dependent operations, adapt the required path, stream or connection before running it.

<?php

$errorCode = 0;
$errorMessage = "";
$server = stream_socket_server("tcp://127.0.0.1:0", $errorCode, $errorMessage);
if ($server === false) { throw new RuntimeException($errorMessage); }
$address = stream_socket_get_name($server, false);
$client = stream_socket_client("tcp://" . $address, $errorCode, $errorMessage, 2);
if ($client === false) { fclose($server); throw new RuntimeException($errorMessage); }
$accepted = stream_socket_accept($server, 2);
if ($accepted === false) { fclose($client); fclose($server); throw new RuntimeException("Accept failed"); }
fwrite($client, "request");
echo fread($accepted, 7);
fclose($accepted); fclose($client); fclose($server);

The important operation is stream_socket_client(). Opens a client connection to a stream transport such as TCP or TLS, with a timeout and context options.

Example 2: Another Input or Scenario

The next example changes the input or surrounding context to show how the operation behaves in a second situation.

<?php

$errorCode = 0;
$errorMessage = "";
$server = stream_socket_server("tcp://127.0.0.1:0", $errorCode, $errorMessage);
if ($server === false) { throw new RuntimeException($errorMessage); }
$address = stream_socket_get_name($server, false);
$client = stream_socket_client("tcp://" . $address, $errorCode, $errorMessage, 2);
if ($client === false) { fclose($server); throw new RuntimeException($errorMessage); }
$accepted = stream_socket_accept($server, 2);
if ($accepted === false) { fclose($client); fclose($server); throw new RuntimeException("Accept failed"); }
fwrite($client, "example");
echo fread($accepted, 7);
fclose($accepted); fclose($client); fclose($server);

Compare the inputs and the handling of the return value with the first example. Avoid assuming that filesystem paths, resource states or binary bytes are interchangeable.

Practical Example: Applying the Operation

This example illustrates how the operation fits into a small application workflow. Paths, streams and secrets must be created or provided securely by the calling application.

<?php

$errorCode = 0;
$errorMessage = "";
$server = stream_socket_server("tcp://127.0.0.1:0", $errorCode, $errorMessage);
if ($server === false) { throw new RuntimeException($errorMessage); }
$address = stream_socket_get_name($server, false);
$client = stream_socket_client("tcp://" . $address, $errorCode, $errorMessage, 2);
if ($client === false) { fclose($server); throw new RuntimeException($errorMessage); }
$accepted = stream_socket_accept($server, 2);
if ($accepted === false) { fclose($client); fclose($server); throw new RuntimeException("Accept failed"); }
fwrite($client, "Health check");
$buffer = fread($accepted, 12);
if ($buffer !== "Health check") { throw new RuntimeException("Unexpected response"); }
fwrite($client, "request");
echo fread($accepted, 7);
fclose($accepted); fclose($client); fclose($server);

Practical note: Opens a client connection to a stream transport such as TCP or TLS, with a timeout and context options.

Important Behavior and Edge Cases

Opens a client connection to a stream transport such as TCP or TLS, with a timeout and context options.
Check failure values and exceptions; do not assume every environment supports the same stream wrapper, extension or filesystem capability.
When handling paths, streams or external input, validate inputs before using results and release resources after use.

Comparison With Related Functions

Function or Method	Behavior
`stream_socket_client()`	initiates an outgoing connection.
`stream_socket_server()`	binds and listens for incoming connections.

Common Beginner Mistakes

Mistake	Correct Approach
Assuming `stream_socket_client()` can be used without its required setup	Provide the correct file, stream, state, key or object before calling it; Opens a client connection to a stream transport such as TCP or TLS, with a timeout and context options.
Assuming one socket read returns the whole message	Treat socket input as a stream and frame messages explicitly; read until a known boundary or length.
Omitting timeouts and failure handling	Check false results, timeouts, and partial writes; close sockets on every error path.

Key Takeaways

stream_socket_client() opens a client connection to a stream transport such as TCP or TLS, with a timeout and context options.
Use appropriate input types and verify results before continuing.
Prefer specialized, safer APIs when the operation concerns untrusted input, encryption or network traffic.

In summary: Opens a client connection to a stream transport such as TCP or TLS, with a timeout and context options. Build in error handling and use this function where its specific behavior matches the application requirements.