Socket Component

Library for building an evented socket server.

The socket component provides a more usable interface for a socket-layer server or client based on the EventLoop and Stream components.

Table of Contents

• Quickstart example
• Usage
  • Server
  • ConnectionInterface
    • getRemoteAddress()
• Install
• Tests
• License

Quickstart example

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

$loop = React\EventLoop\Factory::create();

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

    $conn->on('data', function ($data) use ($conn) {
        $conn->close();
    });
});
$socket->listen(1337);

$loop->run();

You can change the host the socket is listening on through a second parameter provided to the listen method:

$socket->listen(1337, '192.168.0.1');

See also the examples.

Here's a client that outputs the output of said server and then attempts to send it a string. For anything more complex, consider using the SocketClient component instead.

$loop = React\EventLoop\Factory::create();

$client = stream_socket_client('tcp://127.0.0.1:1337');
$conn = new React\Stream\Stream($client, $loop);
$conn->pipe(new React\Stream\Stream(STDOUT, $loop));
$conn->write("Hello World!\n");

$loop->run();

Usage

Server

The Server class is responsible for listening on a port and waiting for new connections.

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

$server->on('connection', function (ConnectionInterface $connection) {
    …
});

ConnectionInterface

The ConnectionInterface is used to represent any incoming connection.

An incoming connection is a duplex stream (both readable and writable) that implements React's DuplexStreamInterface and contains only a single additional property, the remote address (client IP) where this connection has been established from.

Note that this interface is only to be used to represent the server-side end of an incoming connection. It MUST NOT be used to represent an outgoing connection in a client-side context. If you want to establish an outgoing connection, use the SocketClient component instead.

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

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

$conenction->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 remote address (client IP) where this connection has been established from.

$ip = $connection->getRemoteAddress();

It will return the remote address as a string value. 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.

Install

The recommended way to install this library is through Composer. New to Composer?

This will install the latest supported version:

$ composer require react/socket:^0.4.4

More details about version upgrades can be found in the CHANGELOG.

Tests

To run the test suite, you first need to clone this repo and then install all dependencies through Composer. Because the test suite contains some circular dependencies, you may have to manually specify the root package version like this:

$ COMPOSER_ROOT_VERSION=`git describe --abbrev=0` composer install

To run the test suite, you need PHPUnit. Go to the project root and run:

$ phpunit

License

MIT, see LICENSE file.