1: <?php
2:
3: namespace React\Stream;
4:
5: use Evenement\EventEmitterInterface;
6:
7: /**
8: * The `ReadableStreamInterface` is responsible for providing an interface for
9: * read-only streams and the readable side of duplex streams.
10: *
11: * Besides defining a few methods, this interface also implements the
12: * `EventEmitterInterface` which allows you to react to certain events:
13: *
14: * data event:
15: * The `data` event will be emitted whenever some data was read/received
16: * from this source stream.
17: * The event receives a single mixed argument for incoming data.
18: *
19: * ```php
20: * $stream->on('data', function ($data) {
21: * echo $data;
22: * });
23: * ```
24: *
25: * This event MAY be emitted any number of times, which may be zero times if
26: * this stream does not send any data at all.
27: * It SHOULD not be emitted after an `end` or `close` event.
28: *
29: * The given `$data` argument may be of mixed type, but it's usually
30: * recommended it SHOULD be a `string` value or MAY use a type that allows
31: * representation as a `string` for maximum compatibility.
32: *
33: * Many common streams (such as a TCP/IP connection or a file-based stream)
34: * will emit the raw (binary) payload data that is received over the wire as
35: * chunks of `string` values.
36: *
37: * Due to the stream-based nature of this, the sender may send any number
38: * of chunks with varying sizes. There are no guarantees that these chunks
39: * will be received with the exact same framing the sender intended to send.
40: * In other words, many lower-level protocols (such as TCP/IP) transfer the
41: * data in chunks that may be anywhere between single-byte values to several
42: * dozens of kilobytes. You may want to apply a higher-level protocol to
43: * these low-level data chunks in order to achieve proper message framing.
44: *
45: * end event:
46: * The `end` event will be emitted once the source stream has successfully
47: * reached the end of the stream (EOF).
48: *
49: * ```php
50: * $stream->on('end', function () {
51: * echo 'END';
52: * });
53: * ```
54: *
55: * This event SHOULD be emitted once or never at all, depending on whether
56: * a successful end was detected.
57: * It SHOULD NOT be emitted after a previous `end` or `close` event.
58: * It MUST NOT be emitted if the stream closes due to a non-successful
59: * end, such as after a previous `error` event.
60: *
61: * After the stream is ended, it MUST switch to non-readable mode,
62: * see also `isReadable()`.
63: *
64: * This event will only be emitted if the *end* was reached successfully,
65: * not if the stream was interrupted by an unrecoverable error or explicitly
66: * closed. Not all streams know this concept of a "successful end".
67: * Many use-cases involve detecting when the stream closes (terminates)
68: * instead, in this case you should use the `close` event.
69: * After the stream emits an `end` event, it SHOULD usually be followed by a
70: * `close` event.
71: *
72: * Many common streams (such as a TCP/IP connection or a file-based stream)
73: * will emit this event if either the remote side closes the connection or
74: * a file handle was successfully read until reaching its end (EOF).
75: *
76: * Note that this event should not be confused with the `end()` method.
77: * This event defines a successful end *reading* from a source stream, while
78: * the `end()` method defines *writing* a successful end to a destination
79: * stream.
80: *
81: * error event:
82: * The `error` event will be emitted whenever an error occurs, usually while
83: * trying to read from this stream.
84: * The event receives a single `Exception` argument for the error instance.
85: *
86: * ```php
87: * $stream->on('error', function (Exception $e) {
88: * echo 'Error: ' . $e->getMessage() . PHP_EOL;
89: * });
90: * ```
91: *
92: * This event MAY be emitted any number of times, which should be zero
93: * times if this is a stream that is successfully terminated.
94: * It SHOULD be emitted whenever the stream detects an error, such as a
95: * transmission error or after an unexpected `data` or premature `end` event.
96: * It SHOULD NOT be emitted after a `close` event.
97: *
98: * Many common streams (such as a TCP/IP connection or a file-based stream)
99: * only deal with data transmission and do not make assumption about data
100: * boundaries (such as unexpected `data` or premature `end` events).
101: * In other words, many lower-level protocols (such as TCP/IP) may choose
102: * to only emit this for a fatal transmission error once and will thus
103: * likely close (terminate) the stream in response.
104: * If this is a fatal error that results in the stream being closed, it
105: * SHOULD be followed by a `close` event.
106: *
107: * Other higher-level protocols may choose to keep the stream alive after
108: * this event, if they can recover from an error condition.
109: *
110: * If this stream is a `DuplexStreamInterface`, you should also notice
111: * how the writable side of the stream also implements an `error` event.
112: * In other words, an error may occur while either reading or writing the
113: * stream which should result in the same error processing.
114: *
115: * close event:
116: * The `close` event will be emitted once the stream closes (terminates).
117: *
118: * ```php
119: * $stream->on('close', function () {
120: * echo 'CLOSED';
121: * });
122: * ```
123: *
124: * This event SHOULD be emitted once or never at all, depending on whether
125: * the stream ever terminates.
126: * It SHOULD NOT be emitted after a previous `close` event.
127: *
128: * After the stream is closed, it MUST switch to non-readable mode,
129: * see also `isReadable()`.
130: *
131: * Unlike the `end` event, this event SHOULD be emitted whenever the stream
132: * closes, irrespective of whether this happens implicitly due to an
133: * unrecoverable error or explicitly when either side closes the stream.
134: * If you only want to detect a *succesful* end, you should use the `end`
135: * event instead.
136: *
137: * Many common streams (such as a TCP/IP connection or a file-based stream)
138: * will likely choose to emit this event after reading a *successful* `end`
139: * event or after a fatal transmission `error` event.
140: *
141: * If this stream is a `DuplexStreamInterface`, you should also notice
142: * how the writable side of the stream also implements a `close` event.
143: * In other words, after receiving this event, the stream MUST switch into
144: * non-writable AND non-readable mode, see also `isWritable()`.
145: * Note that this event should not be confused with the `end` event.
146: *
147: * @see EventEmitterInterface
148: */
149: interface ReadableStreamInterface extends EventEmitterInterface
150: {
151: /**
152: * Checks whether this stream is in a readable state (not closed already).
153: *
154: * This method can be used to check if the stream still accepts incoming
155: * data events or if it is ended or closed already.
156: * Once the stream is non-readable, no further `data` or `end` events SHOULD
157: * be emitted.
158: *
159: * ```php
160: * assert($stream->isReadable() === false);
161: *
162: * $stream->on('data', assertNeverCalled());
163: * $stream->on('end', assertNeverCalled());
164: * ```
165: *
166: * A successfully opened stream always MUST start in readable mode.
167: *
168: * Once the stream ends or closes, it MUST switch to non-readable mode.
169: * This can happen any time, explicitly through `close()` or
170: * implicitly due to a remote close or an unrecoverable transmission error.
171: * Once a stream has switched to non-readable mode, it MUST NOT transition
172: * back to readable mode.
173: *
174: * If this stream is a `DuplexStreamInterface`, you should also notice
175: * how the writable side of the stream also implements an `isWritable()`
176: * method. Unless this is a half-open duplex stream, they SHOULD usually
177: * have the same return value.
178: *
179: * @return bool
180: */
181: public function isReadable();
182:
183: /**
184: * Pauses reading incoming data events.
185: *
186: * Removes the data source file descriptor from the event loop. This
187: * allows you to throttle incoming data.
188: *
189: * Unless otherwise noted, a successfully opened stream SHOULD NOT start
190: * in paused state.
191: *
192: * Once the stream is paused, no futher `data` or `end` events SHOULD
193: * be emitted.
194: *
195: * ```php
196: * $stream->pause();
197: *
198: * $stream->on('data', assertShouldNeverCalled());
199: * $stream->on('end', assertShouldNeverCalled());
200: * ```
201: *
202: * This method is advisory-only, though generally not recommended, the
203: * stream MAY continue emitting `data` events.
204: *
205: * You can continue processing events by calling `resume()` again.
206: *
207: * Note that both methods can be called any number of times, in particular
208: * calling `pause()` more than once SHOULD NOT have any effect.
209: *
210: * @see self::resume()
211: * @return void
212: */
213: public function pause();
214:
215: /**
216: * Resumes reading incoming data events.
217: *
218: * Re-attach the data source after a previous `pause()`.
219: *
220: * ```php
221: * $stream->pause();
222: *
223: * $loop->addTimer(1.0, function () use ($stream) {
224: * $stream->resume();
225: * });
226: * ```
227: *
228: * Note that both methods can be called any number of times, in particular
229: * calling `resume()` without a prior `pause()` SHOULD NOT have any effect.
230: *
231: * @see self::pause()
232: * @return void
233: */
234: public function resume();
235:
236: /**
237: * Pipes all the data from this readable source into the given writable destination.
238: *
239: * Automatically sends all incoming data to the destination.
240: * Automatically throttles the source based on what the destination can handle.
241: *
242: * ```php
243: * $source->pipe($dest);
244: * ```
245: *
246: * Similarly, you can also pipe an instance implementing `DuplexStreamInterface`
247: * into itself in order to write back all the data that is received.
248: * This may be a useful feature for a TCP/IP echo service:
249: *
250: * ```php
251: * $connection->pipe($connection);
252: * ```
253: *
254: * This method returns the destination stream as-is, which can be used to
255: * set up chains of piped streams:
256: *
257: * ```php
258: * $source->pipe($decodeGzip)->pipe($filterBadWords)->pipe($dest);
259: * ```
260: *
261: * By default, this will call `end()` on the destination stream once the
262: * source stream emits an `end` event. This can be disabled like this:
263: *
264: * ```php
265: * $source->pipe($dest, array('end' => false));
266: * ```
267: *
268: * Note that this only applies to the `end` event.
269: * If an `error` or explicit `close` event happens on the source stream,
270: * you'll have to manually close the destination stream:
271: *
272: * ```php
273: * $source->pipe($dest);
274: * $source->on('close', function () use ($dest) {
275: * $dest->end('BYE!');
276: * });
277: * ```
278: *
279: * If the source stream is not readable (closed state), then this is a NO-OP.
280: *
281: * ```php
282: * $source->close();
283: * $source->pipe($dest); // NO-OP
284: * ```
285: *
286: * If the destinantion stream is not writable (closed state), then this will simply
287: * throttle (pause) the source stream:
288: *
289: * ```php
290: * $dest->close();
291: * $source->pipe($dest); // calls $source->pause()
292: * ```
293: *
294: * Similarly, if the destination stream is closed while the pipe is still
295: * active, it will also throttle (pause) the source stream:
296: *
297: * ```php
298: * $source->pipe($dest);
299: * $dest->close(); // calls $source->pause()
300: * ```
301: *
302: * Once the pipe is set up successfully, the destination stream MUST emit
303: * a `pipe` event with this source stream an event argument.
304: *
305: * @param WritableStreamInterface $dest
306: * @param array $options
307: * @return WritableStreamInterface $dest stream as-is
308: */
309: public function pipe(WritableStreamInterface $dest, array $options = array());
310:
311: /**
312: * Closes the stream (forcefully).
313: *
314: * This method can be used to (forcefully) close the stream.
315: *
316: * ```php
317: * $stream->close();
318: * ```
319: *
320: * Once the stream is closed, it SHOULD emit a `close` event.
321: * Note that this event SHOULD NOT be emitted more than once, in particular
322: * if this method is called multiple times.
323: *
324: * After calling this method, the stream MUST switch into a non-readable
325: * mode, see also `isReadable()`.
326: * This means that no further `data` or `end` events SHOULD be emitted.
327: *
328: * ```php
329: * $stream->close();
330: * assert($stream->isReadable() === false);
331: *
332: * $stream->on('data', assertNeverCalled());
333: * $stream->on('end', assertNeverCalled());
334: * ```
335: *
336: * If this stream is a `DuplexStreamInterface`, you should also notice
337: * how the writable side of the stream also implements a `close()` method.
338: * In other words, after calling this method, the stream MUST switch into
339: * non-writable AND non-readable mode, see also `isWritable()`.
340: * Note that this method should not be confused with the `end()` method.
341: *
342: * @return void
343: * @see WritableStreamInterface::close()
344: */
345: public function close();
346: }
347: