Socket

CI status installs on Packagist

Async, streaming plaintext TCP/IP and secure TLS socket server and client connections for ReactPHP.

The socket library provides re-usable interfaces for a socket-layer server and client based on the EventLoop and Stream components. Its server component allows you to build networking servers that accept incoming connections from networking clients (such as an HTTP server). Its client component allows you to build networking clients that establish outgoing connections to networking servers (such as an HTTP or database client). This library provides async, streaming means for all of this, so you can handle multiple concurrent connections without blocking.

Table of Contents

Quickstart example

Here is a server that closes the connection if you send it anything:

$socket = new React\Socket\SocketServer('127.0.0.1:8080');

$socket->on('connection', function (React\Socket\ConnectionInterface $connection) {
    $connection->write("Hello " . $connection->getRemoteAddress() . "!\n");
    $connection->write("Welcome to this amazing server!\n");
    $connection->write("Here's a tip: don't say anything.\n");

    $connection->on('data', function ($data) use ($connection) {
        $connection->close();
    });
});

See also the examples.

Here's a client that outputs the output of said server and then attempts to send it a string:

$connector = new React\Socket\Connector();

$connector->connect('127.0.0.1:8080')->then(function (React\Socket\ConnectionInterface $connection) {
    $connection->pipe(new React\Stream\WritableResourceStream(STDOUT));
    $connection->write("Hello World!\n");
}, function (Exception $e) {
    echo 'Error: ' . $e->getMessage() . PHP_EOL;
});

Connection usage

ConnectionInterface

The ConnectionInterface is used to represent any incoming and outgoing connection, such as a normal TCP/IP connection.

An incoming or outgoing connection is a duplex stream (both readable and writable) that implements React's DuplexStreamInterface. It contains additional properties for the local and remote address (client IP) where this connection has been established to/from.

Most commonly, instances implementing this ConnectionInterface are emitted by all classes implementing the ServerInterface and used by all classes implementing the ConnectorInterface.

Because the ConnectionInterface implements the underlying DuplexStreamInterface you can use any of its events and methods as usual:

$connection->on('data', function ($chunk) {
    echo $chunk;
});

$connection->on('end', function () {
    echo 'ended';
});

$connection->on('error', function (Exception $e) {
    echo 'error: ' . $e->getMessage();
});

$connection->on('close', function () {
    echo 'closed';
});

$connection->write($data);
$connection->end($data = null);
$connection->close();
// …

For more details, see the DuplexStreamInterface.

getRemoteAddress()

The getRemoteAddress(): ?string method returns the full remote address (URI) where this connection has been established with.

$address = $connection->getRemoteAddress();
echo 'Connection with ' . $address . PHP_EOL;

If the remote address can not be determined or is unknown at this time (such as after the connection has been closed), it MAY return a NULL value instead.

Otherwise, it will return the full address (URI) as a string value, such as tcp://127.0.0.1:8080, tcp://[::1]:80, tls://127.0.0.1:443, unix://example.sock or unix:///path/to/example.sock. Note that individual URI components are application specific and depend on the underlying transport protocol.

If this is a TCP/IP based connection and you only want the remote IP, you may use something like this:

$address = $connection->getRemoteAddress();
$ip = trim(parse_url($address, PHP_URL_HOST), '[]');
echo 'Connection with ' . $ip . PHP_EOL;

getLocalAddress()

The getLocalAddress(): ?string method returns the full local address (URI) where this connection has been established with.

$address = $connection->getLocalAddress();
echo 'Connection with ' . $address . PHP_EOL;

If the local address can not be determined or is unknown at this time (such as after the connection has been closed), it MAY return a NULL value instead.

Otherwise, it will return the full address (URI) as a string value, such as tcp://127.0.0.1:8080, tcp://[::1]:80, tls://127.0.0.1:443, unix://example.sock or unix:///path/to/example.sock. Note that individual URI components are application specific and depend on the underlying transport protocol.

This method complements the getRemoteAddress() method, so they should not be confused.

If your TcpServer instance is listening on multiple interfaces (e.g. using the address 0.0.0.0), you can use this method to find out which interface actually accepted this connection (such as a public or local interface).

If your system has multiple interfaces (e.g. a WAN and a LAN interface), you can use this method to find out which interface was actually used for this connection.

Server usage

ServerInterface

The ServerInterface is responsible for providing an interface for accepting incoming streaming connections, such as a normal TCP/IP connection.

Most higher-level components (such as a HTTP server) accept an instance implementing this interface to accept incoming streaming connections. This is usually done via dependency injection, so it's fairly simple to actually swap this implementation against any other implementation of this interface. This means that you SHOULD typehint against this interface instead of a concrete implementation of this interface.

Besides defining a few methods, this interface also implements the EventEmitterInterface which allows you to react to certain events.

connection event

The connection event will be emitted whenever a new connection has been established, i.e. a new client connects to this server socket:

$socket->on('connection', function (React\Socket\ConnectionInterface $connection) {
    echo 'new connection' . PHP_EOL;
});

See also the ConnectionInterface for more details about handling the incoming connection.

error event

The error event will be emitted whenever there's an error accepting a new connection from a client.

$socket->on('error', function (Exception $e) {
    echo 'error: ' . $e->getMessage() . PHP_EOL;
});

Note that this is not a fatal error event, i.e. the server keeps listening for new connections even after this event.

getAddress()

The getAddress(): ?string method can be used to return the full address (URI) this server is currently listening on.

$address = $socket->getAddress();
echo 'Server listening on ' . $address . PHP_EOL;

If the address can not be determined or is unknown at this time (such as after the socket has been closed), it MAY return a NULL value instead.

Otherwise, it will return the full address (URI) as a string value, such as tcp://127.0.0.1:8080, tcp://[::1]:80, tls://127.0.0.1:443 unix://example.sock or unix:///path/to/example.sock. Note that individual URI components are application specific and depend on the underlying transport protocol.

If this is a TCP/IP based server and you only want the local port, you may use something like this:

$address = $socket->getAddress();
$port = parse_url($address, PHP_URL_PORT);
echo 'Server listening on port ' . $port . PHP_EOL;

pause()

The pause(): void method can be used to pause accepting new incoming connections.

Removes the socket resource from the EventLoop and thus stop accepting new connections. Note that the listening socket stays active and is not closed.

This means that new incoming connections will stay pending in the operating system backlog until its configurable backlog is filled. Once the backlog is filled, the operating system may reject further incoming connections until the backlog is drained again by resuming to accept new connections.

Once the server is paused, no futher connection events SHOULD be emitted.

$socket->pause();

$socket->on('connection', assertShouldNeverCalled());

This method is advisory-only, though generally not recommended, the server MAY continue emitting connection events.

Unless otherwise noted, a successfully opened server SHOULD NOT start in paused state.

You can continue processing events by calling resume() again.

Note that both methods can be called any number of times, in particular calling pause() more than once SHOULD NOT have any effect. Similarly, calling this after close() is a NO-OP.

resume()

The resume(): void method can be used to resume accepting new incoming connections.

Re-attach the socket resource to the EventLoop after a previous pause().

$socket->pause();

Loop::addTimer(1.0, function () use ($socket) {
    $socket->resume();
});

Note that both methods can be called any number of times, in particular calling resume() without a prior pause() SHOULD NOT have any effect. Similarly, calling this after close() is a NO-OP.

close()

The close(): void method can be used to shut down this listening socket.

This will stop listening for new incoming connections on this socket.

echo 'Shutting down server socket' . PHP_EOL;
$socket->close();

Calling this method more than once on the same instance is a NO-OP.

SocketServer

The SocketServer class is the main class in this package that implements the ServerInterface and allows you to accept incoming streaming connections, such as plaintext TCP/IP or secure TLS connection streams.

In order to accept plaintext TCP/IP connections, you can simply pass a host and port combination like this:

$socket = new React\Socket\SocketServer('127.0.0.1:8080');

Listening on the localhost address 127.0.0.1 means it will not be reachable from outside of this system. In order to change the host the socket is listening on, you can provide an IP address of an interface or use the special 0.0.0.0 address to listen on all interfaces:

$socket = new React\Socket\SocketServer('0.0.0.0:8080');

If you want to listen on an IPv6 address, you MUST enclose the host in square brackets:

$socket = new React\Socket\SocketServer('[::1]:8080');

In order to use a random port assignment, you can use the port 0:

$socket = new React\Socket\SocketServer('127.0.0.1:0');
$address = $socket->getAddress();

To listen on a Unix domain socket (UDS) path, you MUST prefix the URI with the unix:// scheme:

$socket = new React\Socket\SocketServer('unix:///tmp/server.sock');

In order to listen on an existing file descriptor (FD) number, you MUST prefix the URI with php://fd/ like this:

$socket = new React\Socket\SocketServer('php://fd/3');

If the given URI is invalid, does not contain a port, any other scheme or if it contains a hostname, it will throw an InvalidArgumentException:

// throws InvalidArgumentException due to missing port
$socket = new React\Socket\SocketServer('127.0.0.1');

If the given URI appears to be valid, but listening on it fails (such as if port is already in use or port below 1024 may require root access etc.), it will throw a RuntimeException:

$first = new React\Socket\SocketServer('127.0.0.1:8080');

// throws RuntimeException because port is already in use
$second = new React\Socket\SocketServer('127.0.0.1:8080');

Note that these error conditions may vary depending on your system and/or configuration. See the exception message and code for more details about the actual error condition.

Optionally, you can specify TCP socket context options for the underlying stream socket resource like this:

$socket = new React\Socket\SocketServer('[::1]:8080', array(
    'tcp' => array(
        'backlog' => 200,
        'so_reuseport' => true,
        'ipv6_v6only' => true
    )
));

Note that available socket context options, their defaults and effects of changing these may vary depending on your system and/or PHP version. Passing unknown context options has no effect. The backlog context option defaults to 511 unless given explicitly.

You can start a secure TLS (formerly known as SSL) server by simply prepending the tls:// URI scheme. Internally, it will wait for plaintext TCP/IP connections and then performs a TLS handshake for each connection. It thus requires valid TLS context options, which in its most basic form may look something like this if you're using a PEM encoded certificate file:

$socket = new React\Socket\SocketServer('tls://127.0.0.1:8080', array(
    'tls' => array(
        'local_cert' => 'server.pem'
    )
));

Note that the certificate file will not be loaded on instantiation but when an incoming connection initializes its TLS context. This implies that any invalid certificate file paths or contents will only cause an error event at a later time.

If your private key is encrypted with a passphrase, you have to specify it like this:

$socket = new React\Socket\SocketServer('tls://127.0.0.1:8000', array(
    'tls' => array(
        'local_cert' => 'server.pem',
        'passphrase' => 'secret'
    )
));

By default, this server supports TLSv1.0+ and excludes support for legacy SSLv2/SSLv3. As of PHP 5.6+ you can also explicitly choose the TLS version you want to negotiate with the remote side:

$socket = new React\Socket\SocketServer('tls://127.0.0.1:8000', array(
    'tls' => array(
        'local_cert' => 'server.pem',
        'crypto_method' => STREAM_CRYPTO_METHOD_TLSv1_2_SERVER
    )
));

Note that available TLS context options, their defaults and effects of changing these may vary depending on your system and/or PHP version. The outer context array allows you to also use tcp (and possibly more) context options at the same time. Passing unknown context options has no effect. If you do not use the tls:// scheme, then passing tls context options has no effect.

Whenever a client connects, it will emit a connection event with a connection instance implementing ConnectionInterface:

$socket->on('connection', function (React\Socket\ConnectionInterface $connection) {
    echo 'Plaintext connection from ' . $connection->getRemoteAddress() . PHP_EOL;
    
    $connection->write('hello there!' . PHP_EOL);
    …
});

See also the ServerInterface for more details.

This class takes an optional LoopInterface|null $loop parameter that can be used to pass the event loop instance to use for this object. You can use a null value here in order to use the default loop. This value SHOULD NOT be given unless you're sure you want to explicitly use a given event loop instance.

Note that the SocketServer class is a concrete implementation for TCP/IP sockets. If you want to typehint in your higher-level protocol implementation, you SHOULD use the generic ServerInterface instead.

Changelog v1.9.0: This class has been added with an improved constructor signature as a replacement for the previous Server class in order to avoid any ambiguities. The previous name has been deprecated and should not be used anymore.

Advanced server usage

TcpServer

The TcpServer class implements the ServerInterface and is responsible for accepting plaintext TCP/IP connections.

$server = new React\Socket\TcpServer(8080);

As above, the $uri parameter can consist of only a port, in which case the server will default to listening on the localhost address 127.0.0.1, which means it will not be reachable from outside of this system.

In order to use a random port assignment, you can use the port 0:

$server = new React\Socket\TcpServer(0);
$address = $server->getAddress();

In order to change the host the socket is listening on, you can provide an IP address through the first parameter provided to the constructor, optionally preceded by the tcp:// scheme:

$server = new React\Socket\TcpServer('192.168.0.1:8080');

If you want to listen on an IPv6 address, you MUST enclose the host in square brackets:

$server = new React\Socket\TcpServer('[::1]:8080');

If the given URI is invalid, does not contain a port, any other scheme or if it contains a hostname, it will throw an InvalidArgumentException:

// throws InvalidArgumentException due to missing port
$server = new React\Socket\TcpServer('127.0.0.1');

If the given URI appears to be valid, but listening on it fails (such as if port is already in use or port below 1024 may require root access etc.), it will throw a RuntimeException:

$first = new React\Socket\TcpServer(8080);

// throws RuntimeException because port is already in use
$second = new React\Socket\TcpServer(8080);

Note that these error conditions may vary depending on your system and/or configuration. See the exception message and code for more details about the actual error condition.

This class takes an optional LoopInterface|null $loop parameter that can be used to pass the event loop instance to use for this object. You can use a null value here in order to use the default loop. This value SHOULD NOT be given unless you're sure you want to explicitly use a given event loop instance.

Optionally, you can specify socket context options for the underlying stream socket resource like this:

$server = new React\Socket\TcpServer('[::1]:8080', null, array(
    'backlog' => 200,
    'so_reuseport' => true,
    'ipv6_v6only' => true
));

Note that available socket context options, their defaults and effects of changing these may vary depending on your system and/or PHP version. Passing unknown context options has no effect. The backlog context option defaults to 511 unless given explicitly.

Whenever a client connects, it will emit a connection event with a connection instance implementing ConnectionInterface:

$server->on('connection', function (React\Socket\ConnectionInterface $connection) {
    echo 'Plaintext connection from ' . $connection->getRemoteAddress() . PHP_EOL;
    
    $connection->write('hello there!' . PHP_EOL);
    …
});

See also the ServerInterface for more details.

SecureServer

The SecureServer class implements the ServerInterface and is responsible for providing a secure TLS (formerly known as SSL) server.

It does so by wrapping a TcpServer instance which waits for plaintext TCP/IP connections and then performs a TLS handshake for each connection. It thus requires valid TLS context options, which in its most basic form may look something like this if you're using a PEM encoded certificate file:

$server = new React\Socket\TcpServer(8000);
$server = new React\Socket\SecureServer($server, null, array(
    'local_cert' => 'server.pem'
));

Note that the certificate file will not be loaded on instantiation but when an incoming connection initializes its TLS context. This implies that any invalid certificate file paths or contents will only cause an error event at a later time.

If your private key is encrypted with a passphrase, you have to specify it like this:

$server = new React\Socket\TcpServer(8000);
$server = new React\Socket\SecureServer($server, null, array(
    'local_cert' => 'server.pem',
    'passphrase' => 'secret'
));

By default, this server supports TLSv1.0+ and excludes support for legacy SSLv2/SSLv3. As of PHP 5.6+ you can also explicitly choose the TLS version you want to negotiate with the remote side: