Subversion Repositories qbpwcf-lib(archive)

# Socket

[![Build Status](https://travis-ci.org/reactphp/socket.svg?branch=master)](https://travis-ci.org/reactphp/socket)

Async, streaming plaintext TCP/IP and secure TLS socket server and client

connections for [ReactPHP](https://reactphp.org/).

The socket library provides re-usable interfaces for a socket-layer

server and client based on the [`EventLoop`](https://github.com/reactphp/event-loop)

and [`Stream`](https://github.com/reactphp/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](#quickstart-example)

* [Connection usage](#connection-usage)

  * [ConnectionInterface](#connectioninterface)

    * [getRemoteAddress()](#getremoteaddress)

    * [getLocalAddress()](#getlocaladdress)

* [Server usage](#server-usage)

  * [ServerInterface](#serverinterface)

    * [connection event](#connection-event)

    * [error event](#error-event)

    * [getAddress()](#getaddress)

    * [pause()](#pause)

    * [resume()](#resume)

    * [close()](#close)

  * [Server](#server)

  * [Advanced server usage](#advanced-server-usage)

    * [TcpServer](#tcpserver)

    * [SecureServer](#secureserver)

    * [UnixServer](#unixserver)

    * [LimitingServer](#limitingserver)

      * [getConnections()](#getconnections)

* [Client usage](#client-usage)

  * [ConnectorInterface](#connectorinterface)

    * [connect()](#connect)

  * [Connector](#connector)

  * [Advanced client usage](#advanced-client-usage)

    * [TcpConnector](#tcpconnector)

    * [HappyEyeBallsConnector](#happyeyeballsconnector)

    * [DnsConnector](#dnsconnector)

    * [SecureConnector](#secureconnector)

    * [TimeoutConnector](#timeoutconnector)

    * [UnixConnector](#unixconnector)

    * [FixUriConnector](#fixeduriconnector)

* [Install](#install)

* [Tests](#tests)

* [License](#license)

## Quickstart example

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

```php

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

$socket = new React\Socket\Server('127.0.0.1:8080', $loop);

$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();

    });

});

$loop->run();

```

See also the [examples](examples).

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

send it a string:

```php

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

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

$connector->connect('127.0.0.1:8080')->then(function (React\Socket\ConnectionInterface $connection) use ($loop) {

    $connection->pipe(new React\Stream\WritableResourceStream(STDOUT, $loop));

    $connection->write("Hello World!\n");

});

$loop->run();

```

## 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`](https://github.com/reactphp/stream#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`](#serverinterface) and

used by all classes implementing the [`ConnectorInterface`](#connectorinterface).

Because the `ConnectionInterface` implements the underlying

[`DuplexStreamInterface`](https://github.com/reactphp/stream#duplexstreaminterface)

you can use any of its events and methods as usual:

```php

$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`](https://github.com/reactphp/stream#duplexstreaminterface).

#### getRemoteAddress()

The `getRemoteAddress(): ?string` method returns the full remote address

(URI) where this connection has been established with.

```php

$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:

```php

$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.

```php

$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()`](#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`](https://github.com/igorw/evenement)

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:

```php

$server->on('connection', function (React\Socket\ConnectionInterface $connection) {

    echo 'new connection' . PHP_EOL;

});

```

See also the [`ConnectionInterface`](#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.

```php

$server->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.

```php

$address = $server->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:

```php

$address = $server->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.

```php

$server->pause();

$server->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()`.

```php

$server->pause();

$loop->addTimer(1.0, function () use ($server) {

    $server->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.

```php

echo 'Shutting down server socket' . PHP_EOL;

$server->close();

```

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

### Server

The `Server` class is the main class in this package that implements the

[`ServerInterface`](#serverinterface) and allows you to accept incoming

streaming connections, such as plaintext TCP/IP or secure TLS connection streams.

Connections can also be accepted on Unix domain sockets.

```php

$server = new React\Socket\Server(8080, $loop);

```

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`:

```php

$server = new React\Socket\Server(0, $loop);

$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:

```php

$server = new React\Socket\Server('192.168.0.1:8080', $loop);

```

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

brackets:

```php

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

```

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

`unix://` scheme:

```php

$server = new React\Socket\Server('unix:///tmp/server.sock', $loop);

```

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`:

```php

// throws InvalidArgumentException due to missing port

$server = new React\Socket\Server('127.0.0.1', $loop);

```

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`:

```php

$first = new React\Socket\Server(8080, $loop);

// throws RuntimeException because port is already in use

$second = new React\Socket\Server(8080, $loop);

```

> 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](https://www.php.net/manual/en/context.socket.php)

for the underlying stream socket resource like this:

```php

$server = new React\Socket\Server('[::1]:8080', $loop, array(

    'tcp' => array(

        'backlog' => 200,

        'so_reuseport' => true,

        'ipv6_v6only' => true

    )

));

```

> Note that available [socket context options](https://www.php.net/manual/en/context.socket.php),

  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.

  For BC reasons, you can also pass the TCP socket context options as a simple

  array without wrapping this in another array under the `tcp` key.

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](https://www.php.net/manual/en/context.ssl.php),

which in its most basic form may look something like this if you're using a

PEM encoded certificate file:

```php

$server = new React\Socket\Server('tls://127.0.0.1:8080', $loop, 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:

```php

$server = new React\Socket\Server('tls://127.0.0.1:8000', $loop, 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:

```php

$server = new React\Socket\Server('tls://127.0.0.1:8000', $loop, array(

    'tls' => array(

        'local_cert' => 'server.pem',

        'crypto_method' => STREAM_CRYPTO_METHOD_TLSv1_2_SERVER

    )

));

```

> Note that available [TLS context options](https://www.php.net/manual/en/context.ssl.php),

  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`](#connectioninterface):

```php

$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`](#serverinterface) for more details.

> Note that the `Server` 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`](#serverinterface) instead.

### Advanced server usage

#### TcpServer

The `TcpServer` class implements the [`ServerInterface`](#serverinterface) and

is responsible for accepting plaintext TCP/IP connections.

```php

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

```

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`:

```php

$server = new React\Socket\TcpServer(0, $loop);

$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:

```php

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

```

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

brackets:

```php

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

```

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`:

```php

// throws InvalidArgumentException due to missing port

$server = new React\Socket\TcpServer('127.0.0.1', $loop);

```

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`:

```php

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

// throws RuntimeException because port is already in use

$second = new React\Socket\TcpServer(8080, $loop);

```

> 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 [socket context options](https://www.php.net/manual/en/context.socket.php)

for the underlying stream socket resource like this:

```php

$server = new React\Socket\TcpServer('[::1]:8080', $loop, array(

    'backlog' => 200,

    'so_reuseport' => true,

    'ipv6_v6only' => true

));

```

> Note that available [socket context options](https://www.php.net/manual/en/context.socket.php),

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`](#connectioninterface):

```php

$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`](#serverinterface) for more details.

#### SecureServer

The `SecureServer` class implements the [`ServerInterface`](#serverinterface)

and is responsible for providing a secure TLS (formerly known as SSL) server.

It does so by wrapping a [`TcpServer`](#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](https://www.php.net/manual/en/context.ssl.php),

which in its most basic form may look something like this if you're using a

PEM encoded certificate file:

```php

$server = new React\Socket\TcpServer(8000, $loop);

$server = new React\Socket\SecureServer($server, $loop, 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:

```php

$server = new React\Socket\TcpServer(8000, $loop);

$server = new React\Socket\SecureServer($server, $loop, 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:

```php

$server = new React\Socket\TcpServer(8000, $loop);

$server = new React\Socket\SecureServer($server, $loop, array(

    'local_cert' => 'server.pem',

    'crypto_method' => STREAM_CRYPTO_METHOD_TLSv1_2_SERVER

));

```

> Note that available [TLS context options](https://www.php.net/manual/en/context.ssl.php),

their defaults and effects of changing these may vary depending on your system

and/or PHP version.

Passing unknown context options has no effect.

Whenever a client completes the TLS handshake, it will emit a `connection` event

with a connection instance implementing [`ConnectionInterface`](#connectioninterface):

```php

$server->on('connection', function (React\Socket\ConnectionInterface $connection) {

    echo 'Secure connection from' . $connection->getRemoteAddress() . PHP_EOL;

    $connection->write('hello there!' . PHP_EOL);

    …

});

```

Whenever a client fails to perform a successful TLS handshake, it will emit an

`error` event and then close the underlying TCP/IP connection:

```php

$server->on('error', function (Exception $e) {

    echo 'Error' . $e->getMessage() . PHP_EOL;

});

```

See also the [`ServerInterface`](#serverinterface) for more details.

Note that the `SecureServer` class is a concrete implementation for TLS sockets.

If you want to typehint in your higher-level protocol implementation, you SHOULD

use the generic [`ServerInterface`](#serverinterface) instead.

> Advanced usage: Despite allowing any `ServerInterface` as first parameter,

you SHOULD pass a `TcpServer` instance as first parameter, unless you

know what you're doing.

Internally, the `SecureServer` has to set the required TLS context options on

the underlying stream resources.

These resources are not exposed through any of the interfaces defined in this

package, but only through the internal `Connection` class.

The `TcpServer` class is guaranteed to emit connections that implement

the `ConnectionInterface` and uses the internal `Connection` class in order to

expose these underlying resources.

If you use a custom `ServerInterface` and its `connection` event does not

meet this requirement, the `SecureServer` will emit an `error` event and

then close the underlying connection.

#### UnixServer

The `UnixServer` class implements the [`ServerInterface`](#serverinterface) and

is responsible for accepting connections on Unix domain sockets (UDS).

```php

$server = new React\Socket\UnixServer('/tmp/server.sock', $loop);

```

As above, the `$uri` parameter can consist of only a socket path or socket path

prefixed by the `unix://` scheme.

If the given URI appears to be valid, but listening on it fails (such as if the

socket is already in use or the file not accessible etc.), it will throw a

`RuntimeException`:

```php

$first = new React\Socket\UnixServer('/tmp/same.sock', $loop);

// throws RuntimeException because socket is already in use

$second = new React\Socket\UnixServer('/tmp/same.sock', $loop);

```

> Note that these error conditions may vary depending on your system and/or

  configuration.

  In particular, Zend PHP does only report "Unknown error" when the UDS path

  already exists and can not be bound. You may want to check `is_file()` on the

  given UDS path to report a more user-friendly error message in this case.

  See the exception message and code for more details about the actual error

  condition.

Whenever a client connects, it will emit a `connection` event with a connection

instance implementing [`ConnectionInterface`](#connectioninterface):

```php

$server->on('connection', function (React\Socket\ConnectionInterface $connection) {

    echo 'New connection' . PHP_EOL;

    $connection->write('hello there!' . PHP_EOL);

    …

});

```

See also the [`ServerInterface`](#serverinterface) for more details.

#### LimitingServer

The `LimitingServer` decorator wraps a given `ServerInterface` and is responsible

for limiting and keeping track of open connections to this server instance.

Whenever the underlying server emits a `connection` event, it will check its

limits and then either

 - keep track of this connection by adding it to the list of

   open connections and then forward the `connection` event

 - or reject (close) the connection when its limits are exceeded and will

   forward an `error` event instead.

Whenever a connection closes, it will remove this connection from the list of

open connections.

```php

$server = new React\Socket\LimitingServer($server, 100);

$server->on('connection', function (React\Socket\ConnectionInterface $connection) {

    $connection->write('hello there!' . PHP_EOL);

    …

});

```

See also the [second example](examples) for more details.

You have to pass a maximum number of open connections to ensure

the server will automatically reject (close) connections once this limit

is exceeded. In this case, it will emit an `error` event to inform about

this and no `connection` event will be emitted.

```php

$server = new React\Socket\LimitingServer($server, 100);

$server->on('connection', function (React\Socket\ConnectionInterface $connection) {

    $connection->write('hello there!' . PHP_EOL);

    …

});

```

You MAY pass a `null` limit in order to put no limit on the number of

open connections and keep accepting new connection until you run out of

operating system resources (such as open file handles). This may be

useful if you do not want to take care of applying a limit but still want

to use the `getConnections()` method.

You can optionally configure the server to pause accepting new

connections once the connection limit is reached. In this case, it will

pause the underlying server and no longer process any new connections at

all, thus also no longer closing any excessive connections.

The underlying operating system is responsible for keeping a backlog of

pending connections until its limit is reached, at which point it will

start rejecting further connections.

Once the server is below the connection limit, it will continue consuming

connections from the backlog and will process any outstanding data on

each connection.

This mode may be useful for some protocols that are designed to wait for

a response message (such as HTTP), but may be less useful for other

protocols that demand immediate responses (such as a "welcome" message in

an interactive chat).

```php

$server = new React\Socket\LimitingServer($server, 100, true);

$server->on('connection', function (React\Socket\ConnectionInterface $connection) {

    $connection->write('hello there!' . PHP_EOL);

    …

});

```

##### getConnections()

The `getConnections(): ConnectionInterface[]` method can be used to

return an array with all currently active connections.

```php

foreach ($server->getConnection() as $connection) {

    $connection->write('Hi!');

}

```

## Client usage

### ConnectorInterface

The `ConnectorInterface` is responsible for providing an interface for

establishing streaming connections, such as a normal TCP/IP connection.

This is the main interface defined in this package and it is used throughout

React's vast ecosystem.

Most higher-level components (such as HTTP, database or other networking

service clients) accept an instance implementing this interface to create their

TCP/IP connection to the underlying networking service.

This is usually done via dependency injection, so it's fairly simple to actually

swap this implementation against any other implementation of this interface.

The interface only offers a single method:

#### connect()

The `connect(string $uri): PromiseInterface<ConnectionInterface,Exception>` method

can be used to create a streaming connection to the given remote address.

It returns a [Promise](https://github.com/reactphp/promise) which either

fulfills with a stream implementing [`ConnectionInterface`](#connectioninterface)

on success or rejects with an `Exception` if the connection is not successful:

```php

$connector->connect('google.com:443')->then(

    function (React\Socket\ConnectionInterface $connection) {

        // connection successfully established

    },

    function (Exception $error) {

        // failed to connect due to $error

    }

);

```

See also [`ConnectionInterface`](#connectioninterface) for more details.

The returned Promise MUST be implemented in such a way that it can be

cancelled when it is still pending. Cancelling a pending promise MUST

reject its value with an `Exception`. It SHOULD clean up any underlying

resources and references as applicable:

```php

$promise = $connector->connect($uri);

$promise->cancel();

```

### Connector

The `Connector` class is the main class in this package that implements the

[`ConnectorInterface`](#connectorinterface) and allows you to create streaming connections.

You can use this connector to create any kind of streaming connections, such

as plaintext TCP/IP, secure TLS or local Unix connection streams.

It binds to the main event loop and can be used like this:

```php

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

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

$connector->connect($uri)->then(function (React\Socket\ConnectionInterface $connection) {

    $connection->write('...');

    $connection->end();

});

$loop->run();

```

In order to create a plaintext TCP/IP connection, you can simply pass a host

and port combination like this:

```php

$connector->connect('www.google.com:80')->then(function (React\Socket\ConnectionInterface $connection) {

    $connection->write('...');

    $connection->end();

});

```

> If you do no specify a URI scheme in the destination URI, it will assume

  `tcp://` as a default and establish a plaintext TCP/IP connection.

  Note that TCP/IP connections require a host and port part in the destination

  URI like above, all other URI components are optional.

In order to create a secure TLS connection, you can use the `tls://` URI scheme

like this:

```php

$connector->connect('tls://www.google.com:443')->then(function (React\Socket\ConnectionInterface $connection) {

    $connection->write('...');

    $connection->end();

});

```

In order to create a local Unix domain socket connection, you can use the

`unix://` URI scheme like this:

```php

$connector->connect('unix:///tmp/demo.sock')->then(function (React\Socket\ConnectionInterface $connection) {

    $connection->write('...');

    $connection->end();

});

```

> The [`getRemoteAddress()`](#getremoteaddress) method will return the target

  Unix domain socket (UDS) path as given to the `connect()` method, including

  the `unix://` scheme, for example `unix:///tmp/demo.sock`.

  The [`getLocalAddress()`](#getlocaladdress) method will most likely return a

  `null` value as this value is not applicable to UDS connections here.

Under the hood, the `Connector` is implemented as a *higher-level facade*

for the lower-level connectors implemented in this package. This means it

also shares all of their features and implementation details.

If you want to typehint in your higher-level protocol implementation, you SHOULD

use the generic [`ConnectorInterface`](#connectorinterface) instead.

As of `v1.4.0`, the `Connector` class defaults to using the

[happy eyeballs algorithm](https://en.wikipedia.org/wiki/Happy_Eyeballs) to

automatically connect over IPv4 or IPv6 when a hostname is given.

This automatically attempts to connect using both IPv4 and IPv6 at the same time

(preferring IPv6), thus avoiding the usual problems faced by users with imperfect

IPv6 connections or setups.

If you want to revert to the old behavior of only doing an IPv4 lookup and

only attempt a single IPv4 connection, you can set up the `Connector` like this:

```php

$connector = new React\Socket\Connector($loop, array(

    'happy_eyeballs' => false

));

```

Similarly, you can also affect the default DNS behavior as follows.

The `Connector` class will try to detect your system DNS settings (and uses

Google's public DNS server `8.8.8.8` as a fallback if unable to determine your

system settings) to resolve all public hostnames into underlying IP addresses by

default.

If you explicitly want to use a custom DNS server (such as a local DNS relay or

a company wide DNS server), you can set up the `Connector` like this:

```php

$connector = new React\Socket\Connector($loop, array(

    'dns' => '127.0.1.1'

));

$connector->connect('localhost:80')->then(function (React\Socket\ConnectionInterface $connection) {

    $connection->write('...');

    $connection->end();

});

```

If you do not want to use a DNS resolver at all and want to connect to IP

addresses only, you can also set up your `Connector` like this:

```php

$connector = new React\Socket\Connector($loop, array(

    'dns' => false

));

$connector->connect('127.0.0.1:80')->then(function (React\Socket\ConnectionInterface $connection) {

    $connection->write('...');

    $connection->end();

});

```

Advanced: If you need a custom DNS `React\Dns\Resolver\ResolverInterface` instance, you

can also set up your `Connector` like this:

```php

$dnsResolverFactory = new React\Dns\Resolver\Factory();

$resolver = $dnsResolverFactory->createCached('127.0.1.1', $loop);

$connector = new React\Socket\Connector($loop, array(

    'dns' => $resolver

));

$connector->connect('localhost:80')->then(function (React\Socket\ConnectionInterface $connection) {

    $connection->write('...');

    $connection->end();

});

```

By default, the `tcp://` and `tls://` URI schemes will use timeout value that

respects your `default_socket_timeout` ini setting (which defaults to 60s).

If you want a custom timeout value, you can simply pass this like this:

```php

$connector = new React\Socket\Connector($loop, array(

    'timeout' => 10.0

));

```

Similarly, if you do not want to apply a timeout at all and let the operating

system handle this, you can pass a boolean flag like this:

```php

$connector = new React\Socket\Connector($loop, array(

    'timeout' => false

));

```

By default, the `Connector` supports the `tcp://`, `tls://` and `unix://`

URI schemes. If you want to explicitly prohibit any of these, you can simply