Socket

Async, streaming plaintext TCP/IP and secure TLS socket server and clientconnections forReactPHP.

The socket library provides re-usable interfaces for a socket-layerserver and client based on theEventLoopandStream components.Its server component allows you to build networking servers that accept incomingconnections from networking clients (such as an HTTP server).Its client component allows you to build networking clients that establishoutgoing connections to networking servers (such as an HTTP or database client).This library provides async, streaming means for all of this, so you canhandle multiple concurrent connections without blocking.

Table of Contents

Quickstart example

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

$socket =newReact\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 theexamples.

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

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

Connection usage

ConnectionInterface

TheConnectionInterface is used to represent any incoming and outgoingconnection, such as a normal TCP/IP connection.

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

Most commonly, instances implementing thisConnectionInterface are emittedby all classes implementing theServerInterface andused by all classes implementing theConnectorInterface.

Because theConnectionInterface implements the underlyingDuplexStreamInterfaceyou 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 theDuplexStreamInterface.

getRemoteAddress()

ThegetRemoteAddress(): ?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 asafter the connection has been closed), it MAY return aNULL value instead.

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

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

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

getLocalAddress()

ThegetLocalAddress(): ?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 asafter the connection has been closed), it MAY return aNULL value instead.

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

If yourTcpServer instance is listening on multiple interfaces (e.g. usingthe address0.0.0.0), you can use this method to find out which interfaceactually 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 actuallyused for this connection.

Server usage

ServerInterface

TheServerInterface is responsible for providing an interface for acceptingincoming streaming connections, such as a normal TCP/IP connection.

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

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

connection event

Theconnection event will be emitted whenever a new connection has beenestablished, 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 theConnectionInterface for more detailsabout handling the incoming connection.

error event

Theerror event will be emitted whenever there's an error accepting a newconnection 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 fornew connections even after this event.

getAddress()

ThegetAddress(): ?string method can be used toreturn 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 asafter the socket has been closed), it MAY return aNULL value instead.

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

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

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

pause()

Thepause(): void method can be used topause accepting new incoming connections.

Removes the socket resource from the EventLoop and thus stop acceptingnew connections. Note that the listening socket stays active and is notclosed.

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

Once the server is paused, no futherconnection events SHOULDbe emitted.

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

This method is advisory-only, though generally not recommended, theserver MAY continue emittingconnection events.

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

You can continue processing events by callingresume() again.

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

resume()

Theresume(): void method can be used toresume accepting new incoming connections.

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

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

Note that both methods can be called any number of times, in particularcallingresume() without a priorpause() SHOULD NOT have any effect.Similarly, calling this afterclose() is a NO-OP.

close()

Theclose(): void method can be used toshut 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

TheSocketServer class is the main class in this package that implements theServerInterface and allows you to accept incomingstreaming connections, such as plaintext TCP/IP or secure TLS connection streams.

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

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

Listening on the localhost address127.0.0.1 means it will not be reachable fromoutside of this system.In order to change the host the socket is listening on, you can provide an IPaddress of an interface or use the special0.0.0.0 address to listen on allinterfaces:

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

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

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

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

$socket =newReact\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 theunix:// scheme:

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

In order to listen on an existing file descriptor (FD) number, you MUST prefixthe URI withphp://fd/ like this:

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

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

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

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

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

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

Optionally, you can specifyTCP socket context optionsfor the underlying stream socket resource like this:

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

Note that availablesocket context options,their defaults and effects of changing these may vary depending on your systemand/or PHP version.Passing unknown context options has no effect.Thebacklog context option defaults to511 unless given explicitly.

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

$socket =newReact\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 anincoming connection initializes its TLS context.This implies that any invalid certificate file paths or contents will only causeanerror event at a later time.

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

$socket =newReact\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 legacySSLv2/SSLv3. As of PHP 5.6+ you can also explicitly choose the TLS version youwant to negotiate with the remote side:

$socket =newReact\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 availableTLS context options,their defaults and effects of changing these may vary depending on your systemand/or PHP version.The outer context array allows you to also usetcp (and possibly more)context options at the same time.Passing unknown context options has no effect.If you do not use thetls:// scheme, then passingtls context optionshas no effect.

Whenever a client connects, it will emit aconnection event with a connectioninstance implementingConnectionInterface:

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

See also theServerInterface for more details.

This class takes an optionalLoopInterface|null $loop parameter that can be used topass the event loop instance to use for this object. You can use anull valuehere in order to use thedefault loop.This value SHOULD NOT be given unless you're sure you want to explicitly use agiven event loop instance.

Note that theSocketServer class is a concrete implementation for TCP/IP sockets.If you want to typehint in your higher-level protocol implementation, you SHOULDuse the genericServerInterface instead.

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

Advanced server usage

TcpServer

TheTcpServer class implements theServerInterface andis responsible for accepting plaintext TCP/IP connections.

$server =newReact\Socket\TcpServer(8080);

As above, the$uri parameter can consist of only a port, in which case theserver will default to listening on the localhost address127.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 port0:

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

In order to change the host the socket is listening on, you can provide an IPaddress through the first parameter provided to the constructor, optionallypreceded by thetcp:// scheme:

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

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

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

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

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

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

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

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

Optionally, you can specifysocket context optionsfor the underlying stream socket resource like this:

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

Note that availablesocket context options,their defaults and effects of changing these may vary depending on your systemand/or PHP version.Passing unknown context options has no effect.Thebacklog context option defaults to511 unless given explicitly.

Whenever a client connects, it will emit aconnection event with a connectioninstance implementingConnectionInterface:

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

See also theServerInterface for more details.

SecureServer

TheSecureServer class implements theServerInterfaceand is responsible for providing a secure TLS (formerly known as SSL) server.

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

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

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

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

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

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

$server =newReact\Socket\TcpServer(8000);$server =newReact\Socket\SecureServer($server,null,array('local_cert' =>'server.pem','crypto_method' => STREAM_CRYPTO_METHOD_TLSv1_2_SERVER));

Note that availableTLS context options,their defaults and effects of changing these may vary depending on your systemand/or PHP version.Passing unknown context options has no effect.

Whenever a client completes the TLS handshake, it will emit aconnection eventwith a connection instance implementingConnectionInterface:

$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 anerror event and then close the underlying TCP/IP connection:

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

See also theServerInterface for more details.

Note that theSecureServer class is a concrete implementation for TLS sockets.If you want to typehint in your higher-level protocol implementation, you SHOULDuse the genericServerInterface instead.

Advanced usage: Despite allowing anyServerInterface as first parameter,you SHOULD pass aTcpServer instance as first parameter, unless youknow what you're doing.Internally, theSecureServer has to set the required TLS context options onthe underlying stream resources.These resources are not exposed through any of the interfaces defined in thispackage, but only through the internalConnection class.TheTcpServer class is guaranteed to emit connections that implementtheConnectionInterface and uses the internalConnection class in order toexpose these underlying resources.If you use a customServerInterface and itsconnection event does notmeet this requirement, theSecureServer will emit anerror event andthen close the underlying connection.

UnixServer

TheUnixServer class implements theServerInterface andis responsible for accepting connections on Unix domain sockets (UDS).

$server =newReact\Socket\UnixServer('/tmp/server.sock');

As above, the$uri parameter can consist of only a socket path or socket pathprefixed by theunix:// scheme.

If the given URI appears to be valid, but listening on it fails (such as if thesocket is already in use or the file not accessible etc.), it will throw aRuntimeException:

$first =newReact\Socket\UnixServer('/tmp/same.sock');// throws RuntimeException because socket is already in use$second =newReact\Socket\UnixServer('/tmp/same.sock');

Note that these error conditions may vary depending on your system and/orconfiguration.In particular, Zend PHP does only report "Unknown error" when the UDS pathalready exists and can not be bound. You may want to checkis_file() on thegiven 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 errorcondition.

Whenever a client connects, it will emit aconnection event with a connectioninstance implementingConnectionInterface:

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

See also theServerInterface for more details.

LimitingServer

TheLimitingServer decorator wraps a givenServerInterface and is responsiblefor limiting and keeping track of open connections to this server instance.

Whenever the underlying server emits aconnection event, it will check itslimits and then either

keep track of this connection by adding it to the list ofopen connections and then forward theconnection event
or reject (close) the connection when its limits are exceeded and willforward anerror event instead.

Whenever a connection closes, it will remove this connection from the list ofopen connections.

$server =newReact\Socket\LimitingServer($server,100);$server->on('connection',function (React\Socket\ConnectionInterface$connection) {$connection->write('hello there!' .PHP_EOL);    …});

See also thesecond example for more details.

You have to pass a maximum number of open connections to ensurethe server will automatically reject (close) connections once this limitis exceeded. In this case, it will emit anerror event to inform aboutthis and noconnection event will be emitted.

$server =newReact\Socket\LimitingServer($server,100);$server->on('connection',function (React\Socket\ConnectionInterface$connection) {$connection->write('hello there!' .PHP_EOL);    …});

You MAY pass anull limit in order to put no limit on the number ofopen connections and keep accepting new connection until you run out ofoperating system resources (such as open file handles). This may beuseful if you do not want to take care of applying a limit but still wantto use thegetConnections() method.

You can optionally configure the server to pause accepting newconnections once the connection limit is reached. In this case, it willpause the underlying server and no longer process any new connections atall, thus also no longer closing any excessive connections.The underlying operating system is responsible for keeping a backlog ofpending connections until its limit is reached, at which point it willstart rejecting further connections.Once the server is below the connection limit, it will continue consumingconnections from the backlog and will process any outstanding data oneach connection.This mode may be useful for some protocols that are designed to wait fora response message (such as HTTP), but may be less useful for otherprotocols that demand immediate responses (such as a "welcome" message inan interactive chat).

$server =newReact\Socket\LimitingServer($server,100,true);$server->on('connection',function (React\Socket\ConnectionInterface$connection) {$connection->write('hello there!' .PHP_EOL);    …});

getConnections()

ThegetConnections(): ConnectionInterface[] method can be used toreturn an array with all currently active connections.

foreach ($server->getConnection()as$connection) {$connection->write('Hi!');}

Client usage

ConnectorInterface

TheConnectorInterface is responsible for providing an interface forestablishing streaming connections, such as a normal TCP/IP connection.

This is the main interface defined in this package and it is used throughoutReact's vast ecosystem.

Most higher-level components (such as HTTP, database or other networkingservice clients) accept an instance implementing this interface to create theirTCP/IP connection to the underlying networking service.This is usually done via dependency injection, so it's fairly simple to actuallyswap this implementation against any other implementation of this interface.

The interface only offers a single method:

connect()

Theconnect(string $uri): PromiseInterface<ConnectionInterface> method can be used tocreate a streaming connection to the given remote address.

It returns aPromise which eitherfulfills with a stream implementingConnectionInterfaceon success or rejects with anException if the connection is not successful:

$connector->connect('google.com:443')->then(function (React\Socket\ConnectionInterface$connection) {// connection successfully established    },function (Exception$error) {// failed to connect due to $error    });

See alsoConnectionInterface for more details.

The returned Promise MUST be implemented in such a way that it can becancelled when it is still pending. Cancelling a pending promise MUSTreject its value with anException. It SHOULD clean up any underlyingresources and references as applicable:

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

Connector

TheConnector class is the main class in this package that implements theConnectorInterface and allows you to create streaming connections.

You can use this connector to create any kind of streaming connections, suchas plaintext TCP/IP, secure TLS or local Unix connection streams.

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

$connector =newReact\Socket\Connector();$connector->connect($uri)->then(function (React\Socket\ConnectionInterface$connection) {$connection->write('...');$connection->end();},function (Exception$e) {echo'Error:' .$e->getMessage() .PHP_EOL;});

In order to create a plaintext TCP/IP connection, you can simply pass a hostand port combination like this:

$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 assumetcp:// as a default and establish a plaintext TCP/IP connection.Note that TCP/IP connections require a host and port part in the destinationURI like above, all other URI components are optional.

In order to create a secure TLS connection, you can use thetls:// URI schemelike this:

$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 theunix:// URI scheme like this:

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

ThegetRemoteAddress() method will return the targetUnix domain socket (UDS) path as given to theconnect() method, includingtheunix:// scheme, for exampleunix:///tmp/demo.sock.ThegetLocalAddress() method will most likely return anull value as this value is not applicable to UDS connections here.

Under the hood, theConnector is implemented as ahigher-level facadefor the lower-level connectors implemented in this package. This means italso shares all of their features and implementation details.If you want to typehint in your higher-level protocol implementation, you SHOULDuse the genericConnectorInterface instead.

As ofv1.4.0, theConnector class defaults to using thehappy eyeballs algorithm toautomatically 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 imperfectIPv6 connections or setups.If you want to revert to the old behavior of only doing an IPv4 lookup andonly attempt a single IPv4 connection, you can set up theConnector like this:

$connector =newReact\Socket\Connector(array('happy_eyeballs' =>false));

Similarly, you can also affect the default DNS behavior as follows.TheConnector class will try to detect your system DNS settings (and usesGoogle's public DNS server8.8.8.8 as a fallback if unable to determine yoursystem settings) to resolve all public hostnames into underlying IP addresses bydefault.If you explicitly want to use a custom DNS server (such as a local DNS relay ora company wide DNS server), you can set up theConnector like this:

$connector =newReact\Socket\Connector(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 IPaddresses only, you can also set up yourConnector like this:

$connector =newReact\Socket\Connector(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 DNSReact\Dns\Resolver\ResolverInterface instance, youcan also set up yourConnector like this:

$dnsResolverFactory =newReact\Dns\Resolver\Factory();$resolver =$dnsResolverFactory->createCached('127.0.1.1');$connector =newReact\Socket\Connector(array('dns' =>$resolver));$connector->connect('localhost:80')->then(function (React\Socket\ConnectionInterface$connection) {$connection->write('...');$connection->end();});

By default, thetcp:// andtls:// URI schemes will use timeout value thatrespects yourdefault_socket_timeout ini setting (which defaults to 60s).If you want a custom timeout value, you can simply pass this like this:

$connector =newReact\Socket\Connector(array('timeout' =>10.0));

Similarly, if you do not want to apply a timeout at all and let the operatingsystem handle this, you can pass a boolean flag like this:

$connector =newReact\Socket\Connector(array('timeout' =>false));

By default, theConnector supports thetcp://,tls:// andunix://URI schemes. If you want to explicitly prohibit any of these, you can simplypass boolean flags like this:

// only allow secure TLS connections$connector =newReact\Socket\Connector(array('tcp' =>false,'tls' =>true,'unix' =>false,));$connector->connect('tls://google.com:443')->then(function (React\Socket\ConnectionInterface$connection) {$connection->write('...');$connection->end();});

Thetcp:// andtls:// also accept additional context options passed tothe underlying connectors.If you want to explicitly pass additional context options, you can simplypass arrays of context options like this:

// allow insecure TLS connections$connector =newReact\Socket\Connector(array('tcp' =>array('bindto' =>'192.168.0.1:0'    ),'tls' =>array('verify_peer' =>false,'verify_peer_name' =>false    ),));$connector->connect('tls://localhost:443')->then(function (React\Socket\ConnectionInterface$connection) {$connection->write('...');$connection->end();});

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

$connector =newReact\Socket\Connector(array('tls' =>array('crypto_method' => STREAM_CRYPTO_METHOD_TLSv1_2_CLIENT    )));

For more details about context options, please refer to the PHP documentationaboutsocket context optionsandSSL context options.

Advanced: By default, theConnector supports thetcp://,tls:// andunix:// URI schemes.For this, it sets up the required connector classes automatically.If you want to explicitly pass custom connectors for any of these, you can simplypass an instance implementing theConnectorInterface like this:

$dnsResolverFactory =newReact\Dns\Resolver\Factory();$resolver =$dnsResolverFactory->createCached('127.0.1.1');$tcp =newReact\Socket\HappyEyeBallsConnector(null,newReact\Socket\TcpConnector(),$resolver);$tls =newReact\Socket\SecureConnector($tcp);$unix =newReact\Socket\UnixConnector();$connector =newReact\Socket\Connector(array('tcp' =>$tcp,'tls' =>$tls,'unix' =>$unix,'dns' =>false,'timeout' =>false,));$connector->connect('google.com:80')->then(function (React\Socket\ConnectionInterface$connection) {$connection->write('...');$connection->end();});

Internally, thetcp:// connector will always be wrapped by the DNS resolver,unless you disable DNS like in the above example. In this case, thetcp://connector receives the actual hostname instead of only the resolved IP addressand is thus responsible for performing the lookup.Internally, the automatically createdtls:// connector will always wrap theunderlyingtcp:// connector for establishing the underlying plaintextTCP/IP connection before enabling secure TLS mode. If you want to use a customunderlyingtcp:// connector for secure TLS connections only, you mayexplicitly pass atls:// connector like above instead.Internally, thetcp:// andtls:// connectors will always be wrapped byTimeoutConnector, unless you disable timeouts like in the above example.

Changelog v1.9.0: The constructur signature has been updated to take theoptional$context as the first parameter and the optional$loop as a secondargument. The previous signature has been deprecated and should not be used anymore.
// constructor signature as of v1.9.0$connector =newReact\Socket\Connector(array$context = [], ?LoopInterface$loop =null);// legacy constructor signature before v1.9.0$connector =newReact\Socket\Connector(?LoopInterface$loop =null, array$context = []);

Advanced client usage

TcpConnector

TheTcpConnector class implements theConnectorInterface and allows you to create plaintextTCP/IP connections to any IP-port-combination:

$tcpConnector =newReact\Socket\TcpConnector();$tcpConnector->connect('127.0.0.1:80')->then(function (React\Socket\ConnectionInterface$connection) {$connection->write('...');$connection->end();});

See also theexamples.

Pending connection attempts can be cancelled by cancelling its pending promise like so:

$promise =$tcpConnector->connect('127.0.0.1:80');$promise->cancel();

Callingcancel() on a pending promise will close the underlying socketresource, thus cancelling the pending TCP/IP connection, and reject theresulting promise.

You can optionally pass additionalsocket context optionsto the constructor like this:

$tcpConnector =newReact\Socket\TcpConnector(null,array('bindto' =>'192.168.0.1:0'));

Note that this class only allows you to connect to IP-port-combinations.If the given URI is invalid, does not contain a valid IP address and portor contains any other scheme, it will reject with anInvalidArgumentException:

If the given URI appears to be valid, but connecting to it fails (such as ifthe remote host rejects the connection etc.), it will reject with aRuntimeException.

If you want to connect to hostname-port-combinations, see also the following chapter.

Advanced usage: Internally, theTcpConnector allocates an emptycontextresource for each stream resource.If the destination URI contains ahostname query parameter, its value willbe used to set up the TLS peer name.This is used by theSecureConnector andDnsConnector to verify the peername and can also be used if you want a custom TLS peer name.

HappyEyeBallsConnector

TheHappyEyeBallsConnector class implements theConnectorInterface and allows you to create plaintextTCP/IP connections to any hostname-port-combination. Internally it implements thehappy eyeballs algorithm fromRFC6555 andRFC8305 to support IPv6 and IPv4 hostnames.

It does so by decorating a givenTcpConnector instance so that it firstlooks up the given domain name via DNS (if applicable) and then establishes theunderlying TCP/IP connection to the resolved target IP address.

Make sure to set up your DNS resolver and underlying TCP connector like this:

$dnsResolverFactory =newReact\Dns\Resolver\Factory();$dns =$dnsResolverFactory->createCached('8.8.8.8');$dnsConnector =newReact\Socket\HappyEyeBallsConnector(null,$tcpConnector,$dns);$dnsConnector->connect('www.google.com:80')->then(function (React\Socket\ConnectionInterface$connection) {$connection->write('...');$connection->end();});

See also theexamples.

Pending connection attempts can be cancelled by cancelling its pending promise like so:

$promise =$dnsConnector->connect('www.google.com:80');$promise->cancel();

Callingcancel() on a pending promise will cancel the underlying DNS lookupsand/or the underlying TCP/IP connection(s) and reject the resulting promise.

Advanced usage: Internally, theHappyEyeBallsConnector relies on aResolver tolook up the IP addresses for the given hostname.It will then replace the hostname in the destination URI with this IP's andappend ahostname query parameter and pass this updated URI to the underlyingconnector.The Happy Eye Balls algorithm describes looking the IPv6 and IPv4 address forthe given hostname so this connector sends out two DNS lookups for the A andAAAA records. It then uses all IP addresses (both v6 and v4) and tries toconnect to all of them with a 50ms interval in between. Alterating between IPv6and IPv4 addresses. When a connection is established all the other DNS lookupsand connection attempts are cancelled.

DnsConnector

TheDnsConnector class implements theConnectorInterface and allows you to create plaintextTCP/IP connections to any hostname-port-combination.

Make sure to set up your DNS resolver and underlying TCP connector like this:

$dnsResolverFactory =newReact\Dns\Resolver\Factory();$dns =$dnsResolverFactory->createCached('8.8.8.8');$dnsConnector =newReact\Socket\DnsConnector($tcpConnector,$dns);$dnsConnector->connect('www.google.com:80')->then(function (React\Socket\ConnectionInterface$connection) {$connection->write('...');$connection->end();});

See also theexamples.

Pending connection attempts can be cancelled by cancelling its pending promise like so:

$promise =$dnsConnector->connect('www.google.com:80');$promise->cancel();

Callingcancel() on a pending promise will cancel the underlying DNS lookupand/or the underlying TCP/IP connection and reject the resulting promise.

Advanced usage: Internally, theDnsConnector relies on aReact\Dns\Resolver\ResolverInterfaceto look up the IP address for the given hostname.It will then replace the hostname in the destination URI with this IP andappend ahostname query parameter and pass this updated URI to the underlyingconnector.The underlying connector is thus responsible for creating a connection to thetarget IP address, while this query parameter can be used to check the originalhostname and is used by theTcpConnector to set up the TLS peer name.If ahostname is given explicitly, this query parameter will not be modified,which can be useful if you want a custom TLS peer name.

SecureConnector

TheSecureConnector class implements theConnectorInterface and allows you to create secureTLS (formerly known as SSL) connections to any hostname-port-combination.

It does so by decorating a givenDnsConnector instance so that it firstcreates a plaintext TCP/IP connection and then enables TLS encryption on thisstream.

$secureConnector =newReact\Socket\SecureConnector($dnsConnector);$secureConnector->connect('www.google.com:443')->then(function (React\Socket\ConnectionInterface$connection) {$connection->write("GET / HTTP/1.0\r\nHost: www.google.com\r\n\r\n");...});

See also theexamples.

Pending connection attempts can be cancelled by cancelling its pending promise like so:

$promise =$secureConnector->connect('www.google.com:443');$promise->cancel();

Callingcancel() on a pending promise will cancel the underlying TCP/IPconnection and/or the SSL/TLS negotiation and reject the resulting promise.

You can optionally pass additionalSSL context optionsto the constructor like this:

$secureConnector =newReact\Socket\SecureConnector($dnsConnector,null,array('verify_peer' =>false,'verify_peer_name' =>false));

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

$secureConnector =newReact\Socket\SecureConnector($dnsConnector,null,array('crypto_method' => STREAM_CRYPTO_METHOD_TLSv1_2_CLIENT));

Advanced usage: Internally, theSecureConnector relies on setting up therequiredcontext options on the underlying stream resource.It should therefor be used with aTcpConnector somewhere in the connectorstack so that it can allocate an emptycontext resource for each streamresource and verify the peer name.Failing to do so may result in a TLS peer name mismatch error or some hard totrace race conditions, because all stream resources will use a single, shareddefault context resource otherwise.

TimeoutConnector

TheTimeoutConnector class implements theConnectorInterface and allows you to add timeouthandling to any existing connector instance.

It does so by decorating any givenConnectorInterfaceinstance and starting a timer that will automatically reject and abort anyunderlying connection attempt if it takes too long.

$timeoutConnector =newReact\Socket\TimeoutConnector($connector,3.0);$timeoutConnector->connect('google.com:80')->then(function (React\Socket\ConnectionInterface$connection) {// connection succeeded within 3.0 seconds});

UnixConnector

TheUnixConnector class implements theConnectorInterface and allows you to connect toUnix domain socket (UDS) paths like this:

$connector =newReact\Socket\UnixConnector();$connector->connect('/tmp/demo.sock')->then(function (React\Socket\ConnectionInterface$connection) {$connection->write("HELLO\n");});

Connecting to Unix domain sockets is an atomic operation, i.e. its promise willsettle (either resolve or reject) immediately.As such, callingcancel() on the resulting promise has no effect.

ThegetRemoteAddress() method will return the targetUnix domain socket (UDS) path as given to theconnect() method, prependedwith theunix:// scheme, for exampleunix:///tmp/demo.sock.ThegetLocalAddress() method will most likely return anull value as this value is not applicable to UDS connections here.

FixedUriConnector

TheFixedUriConnector class implements theConnectorInterface and decorates an existing Connectorto always use a fixed, preconfigured URI.

This can be useful for consumers that do not support certain URIs, such aswhen you want to explicitly connect to a Unix domain socket (UDS) pathinstead of connecting to a default address assumed by an higher-level API:

$connector =newReact\Socket\FixedUriConnector('unix:///var/run/docker.sock',newReact\Socket\UnixConnector());// destination will be ignored, actually connects to Unix domain socket$promise =$connector->connect('localhost:80');

Install

The recommended way to install this library isthrough Composer.New to Composer?

This project followsSemVer.This will install the latest supported version:

composer require react/socket:^1.16

See also theCHANGELOG for details about version upgrades.

This project aims to run on any platform and thus does not require any PHPextensions and supports running on legacy PHP 5.3 through current PHP 8+ and HHVM.It'shighly recommended to use the latest supported PHP version for this project,partly due to its vast performance improvements and partly because legacy PHPversions require several workarounds as described below.

Secure TLS connections received some major upgrades starting with PHP 5.6, withthe defaults now being more secure, while older versions required explicitcontext options.This library does not take responsibility over these context options, so it'sup to consumers of this library to take care of setting appropriate contextoptions as described above.

PHP < 7.3.3 (and PHP < 7.2.15) suffers from a bug where feof() mightblock with 100% CPU usage on fragmented TLS records.We try to work around this by always consuming the complete receivebuffer at once to avoid stale data in TLS buffers. This is known towork around high CPU usage for well-behaving peers, but this maycause very large data chunks for high throughput scenarios. The buggybehavior can still be triggered due to network I/O buffers ormalicious peers on affected versions, upgrading is highly recommended.

PHP < 7.1.4 (and PHP < 7.0.18) suffers from a bug when writing bigchunks of data over TLS streams at once.We try to work around this by limiting the write chunk size to 8192bytes for older PHP versions only.This is only a work-around and has a noticable performance penalty onaffected versions.

This project also supports running on HHVM.Note that really old HHVM < 3.8 does not support secure TLS connections, as itlacks the requiredstream_socket_enable_crypto() function.As such, trying to create a secure TLS connections on affected versions willreturn a rejected promise instead.This issue is also covered by our test suite, which will skip related testson affected versions.

Tests

To run the test suite, you first need to clone this repo and then install alldependenciesthrough Composer:

composer install

To run the test suite, go to the project root and run:

vendor/bin/phpunit

The test suite also contains a number of functional integration tests that relyon a stable internet connection.If you do not want to run these, they can simply be skipped like this:

vendor/bin/phpunit --exclude-group internet

License

MIT, seeLICENSE file.

Movatterモバイル変換

Socket

Socket

Quickstart example

Connection usage

ConnectionInterface

getRemoteAddress()

getLocalAddress()

Server usage

ServerInterface

connection event

error event

getAddress()

pause()

resume()

close()

SocketServer

Advanced server usage

TcpServer

SecureServer

UnixServer

LimitingServer

getConnections()

Client usage

ConnectorInterface

connect()

Connector

Advanced client usage

TcpConnector

HappyEyeBallsConnector

DnsConnector

SecureConnector

TimeoutConnector

UnixConnector

FixedUriConnector

Install

Tests

License

Installation

Contributors

Activity