ServerInterface
extends
EventEmitterInterface
in
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:
```php
$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.
```php
$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.
Tags
Table of Contents
Methods
- close() : void
- Shuts down this listening socket
- emit() : mixed
- getAddress() : string|null
- Returns the full address (URI) this server is currently listening on
- listeners() : mixed
- on() : mixed
- once() : mixed
- pause() : void
- Pauses accepting new incoming connections.
- removeAllListeners() : mixed
- removeListener() : mixed
- resume() : void
- Resumes accepting new incoming connections.
Methods
close()
Shuts down this listening socket
public
close() : void
This will stop listening for new incoming connections on this socket.
Calling this method more than once on the same instance is a NO-OP.
emit()
public
emit(mixed $event[, array<string|int, mixed> $arguments = [] ]) : mixed
Parameters
- $event : mixed
- $arguments : array<string|int, mixed> = []
getAddress()
Returns the full address (URI) this server is currently listening on
public
getAddress() : string|null
$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 or tls://127.0.0.1:443.
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;
Return values
string|null —the full listening address (URI) or NULL if it is unknown (not applicable to this server socket or already closed)
listeners()
public
listeners([mixed $event = null ]) : mixed
Parameters
- $event : mixed = null
on()
public
on(mixed $event, callable $listener) : mixed
Parameters
- $event : mixed
- $listener : callable
once()
public
once(mixed $event, callable $listener) : mixed
Parameters
- $event : mixed
- $listener : callable
pause()
Pauses accepting new incoming connections.
public
pause() : void
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.
Tags
removeAllListeners()
public
removeAllListeners([mixed $event = null ]) : mixed
Parameters
- $event : mixed = null
removeListener()
public
removeListener(mixed $event, callable $listener) : mixed
Parameters
- $event : mixed
- $listener : callable
resume()
Resumes accepting new incoming connections.
public
resume() : void
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.