friendship ended with social-app. php is my new best friend
veryroundbird.house
1<?php
2
3namespace React\Socket;
4
5use Evenement\EventEmitterInterface;
6
7/**
8 * The `ServerInterface` is responsible for providing an interface for accepting
9 * incoming streaming connections, such as a normal TCP/IP connection.
10 *
11 * Most higher-level components (such as a HTTP server) accept an instance
12 * implementing this interface to accept incoming streaming connections.
13 * This is usually done via dependency injection, so it's fairly simple to actually
14 * swap this implementation against any other implementation of this interface.
15 * This means that you SHOULD typehint against this interface instead of a concrete
16 * implementation of this interface.
17 *
18 * Besides defining a few methods, this interface also implements the
19 * `EventEmitterInterface` which allows you to react to certain events:
20 *
21 * connection event:
22 * The `connection` event will be emitted whenever a new connection has been
23 * established, i.e. a new client connects to this server socket:
24 *
25 * ```php
26 * $socket->on('connection', function (React\Socket\ConnectionInterface $connection) {
27 * echo 'new connection' . PHP_EOL;
28 * });
29 * ```
30 *
31 * See also the `ConnectionInterface` for more details about handling the
32 * incoming connection.
33 *
34 * error event:
35 * The `error` event will be emitted whenever there's an error accepting a new
36 * connection from a client.
37 *
38 * ```php
39 * $socket->on('error', function (Exception $e) {
40 * echo 'error: ' . $e->getMessage() . PHP_EOL;
41 * });
42 * ```
43 *
44 * Note that this is not a fatal error event, i.e. the server keeps listening for
45 * new connections even after this event.
46 *
47 * @see ConnectionInterface
48 */
49interface ServerInterface extends EventEmitterInterface
50{
51 /**
52 * Returns the full address (URI) this server is currently listening on
53 *
54 * ```php
55 * $address = $socket->getAddress();
56 * echo 'Server listening on ' . $address . PHP_EOL;
57 * ```
58 *
59 * If the address can not be determined or is unknown at this time (such as
60 * after the socket has been closed), it MAY return a `NULL` value instead.
61 *
62 * Otherwise, it will return the full address (URI) as a string value, such
63 * as `tcp://127.0.0.1:8080`, `tcp://[::1]:80` or `tls://127.0.0.1:443`.
64 * Note that individual URI components are application specific and depend
65 * on the underlying transport protocol.
66 *
67 * If this is a TCP/IP based server and you only want the local port, you may
68 * use something like this:
69 *
70 * ```php
71 * $address = $socket->getAddress();
72 * $port = parse_url($address, PHP_URL_PORT);
73 * echo 'Server listening on port ' . $port . PHP_EOL;
74 * ```
75 *
76 * @return ?string the full listening address (URI) or NULL if it is unknown (not applicable to this server socket or already closed)
77 */
78 public function getAddress();
79
80 /**
81 * Pauses accepting new incoming connections.
82 *
83 * Removes the socket resource from the EventLoop and thus stop accepting
84 * new connections. Note that the listening socket stays active and is not
85 * closed.
86 *
87 * This means that new incoming connections will stay pending in the
88 * operating system backlog until its configurable backlog is filled.
89 * Once the backlog is filled, the operating system may reject further
90 * incoming connections until the backlog is drained again by resuming
91 * to accept new connections.
92 *
93 * Once the server is paused, no futher `connection` events SHOULD
94 * be emitted.
95 *
96 * ```php
97 * $socket->pause();
98 *
99 * $socket->on('connection', assertShouldNeverCalled());
100 * ```
101 *
102 * This method is advisory-only, though generally not recommended, the
103 * server MAY continue emitting `connection` events.
104 *
105 * Unless otherwise noted, a successfully opened server SHOULD NOT start
106 * in paused state.
107 *
108 * You can continue processing events by calling `resume()` again.
109 *
110 * Note that both methods can be called any number of times, in particular
111 * calling `pause()` more than once SHOULD NOT have any effect.
112 * Similarly, calling this after `close()` is a NO-OP.
113 *
114 * @see self::resume()
115 * @return void
116 */
117 public function pause();
118
119 /**
120 * Resumes accepting new incoming connections.
121 *
122 * Re-attach the socket resource to the EventLoop after a previous `pause()`.
123 *
124 * ```php
125 * $socket->pause();
126 *
127 * Loop::addTimer(1.0, function () use ($socket) {
128 * $socket->resume();
129 * });
130 * ```
131 *
132 * Note that both methods can be called any number of times, in particular
133 * calling `resume()` without a prior `pause()` SHOULD NOT have any effect.
134 * Similarly, calling this after `close()` is a NO-OP.
135 *
136 * @see self::pause()
137 * @return void
138 */
139 public function resume();
140
141 /**
142 * Shuts down this listening socket
143 *
144 * This will stop listening for new incoming connections on this socket.
145 *
146 * Calling this method more than once on the same instance is a NO-OP.
147 *
148 * @return void
149 */
150 public function close();
151}