Download the PHP package matasarei/php-tcp without Composer

PHP TCP Client

A lightweight TCP client for PHP with no runtime dependencies beyond a PSR-3 logger interface. It wraps PHP's native stream functions in a small, testable API: pluggable socket transports, configurable timeouts, optional delimiter-based response framing and PSR-3 logging.

Well suited for simple text-based request/response protocols — line-delimited JSON, JSON-RPC over TCP, custom device or legacy service protocols, and similar.

Features

• Simple connect / request / disconnect API over plain TCP
• Two built-in transports — StreamSocket (stream_socket_client) and FSocket (fsockopen) — plus a one-method SocketInterface for custom transports
• Optional end-of-response delimiter for line-based protocols (see Response framing)
• Detects broken streams and connections closed by the peer; completes partial writes
• Configurable connection, request and read timeouts, fractions of a second included
• A response size limit, so a peer that keeps sending cannot exhaust memory (8 MiB by default)
• PSR-3 (psr/log v1, v2 or v3) logger support for debugging

Requirements

• PHP 7.4 or newer

Installation

Quick start

Request accepts an optional per-request timeout in seconds (default 30):

Socket transports

The library includes two transports: StreamSocket and FSocket. The difference is stream_socket_client() vs fsockopen() under the hood; pick whichever you prefer, or implement Socket\SocketInterface to supply your own (e.g. for TLS wrappers or unit-test stubs).

Both transports take a read timeout (seconds, default 1) that controls how long a single read waits for data before reporting "no data yet", and an optional blocking flag:

The second argument defaults to null, which means "blocking when the timeout is positive" — the rule the first argument used to decide on its own.

The host is the address only: a value carrying a scheme, such as udp://198.51.100.7, is rejected rather than quietly opening something other than a TCP socket. IPv6 literals are accepted as-is (::1).

Client settings

Response framing

By default, the client considers a response complete when the server stops sending data for a moment (a silent interval on the stream). This works without any protocol knowledge, but it has two downsides: every read costs an extra blocking-timeout interval, and a server that stalls mid-response can have its reply cut short.

If your protocol marks the end of a message — like line-based protocols such as JSON-RPC over TCP — set a delimiter instead:

With a delimiter set, the client returns as soon as the response ends with the delimiter (the delimiter is kept in the response data). It throws a RequestException if a complete response does not arrive within the request timeout, and a ConnectionException if the connection is closed before the response is completed.

Error handling

All exceptions live under Matasar\PhpTcp\Exception:

Testing

The test suite runs against PHP 7.4–8.5 in CI.

Locally, the easiest way is Docker — no PHP or Composer installation required:

Or with a local PHP setup:

To check the dependencies against published advisories:

License

Released under the MIT license.