Debian Codegraph @

vendor/react/stream/src/ThroughStream.php

raw
1 <?php
2
3 namespace React\Stream;
4
5 use Evenement\EventEmitter;
6 use InvalidArgumentException;
7
8 /**
9 * The `ThroughStream` implements the
10 * [`DuplexStreamInterface`](#duplexstreaminterface) and will simply pass any data
11 * you write to it through to its readable end.
12 *
13 * ```php
14 * $through = new ThroughStream();
15 * $through->on('data', $this->expectCallableOnceWith('hello'));
16 *
17 * $through->write('hello');
18 * ```
19 *
20 * Similarly, the [`end()` method](#end) will end the stream and emit an
21 * [`end` event](#end-event) and then [`close()`](#close-1) the stream.
22 * The [`close()` method](#close-1) will close the stream and emit a
23 * [`close` event](#close-event).
24 * Accordingly, this is can also be used in a [`pipe()`](#pipe) context like this:
25 *
26 * ```php
27 * $through = new ThroughStream();
28 * $source->pipe($through)->pipe($dest);
29 * ```
30 *
31 * Optionally, its constructor accepts any callable function which will then be
32 * used to *filter* any data written to it. This function receives a single data
33 * argument as passed to the writable side and must return the data as it will be
34 * passed to its readable end:
35 *
36 * ```php
37 * $through = new ThroughStream('strtoupper');
38 * $source->pipe($through)->pipe($dest);
39 * ```
40 *
41 * Note that this class makes no assumptions about any data types. This can be
42 * used to convert data, for example for transforming any structured data into
43 * a newline-delimited JSON (NDJSON) stream like this:
44 *
45 * ```php
46 * $through = new ThroughStream(function ($data) {
47 * return json_encode($data) . PHP_EOL;
48 * });
49 * $through->on('data', $this->expectCallableOnceWith("[2, true]\n"));
50 *
51 * $through->write(array(2, true));
52 * ```
53 *
54 * The callback function is allowed to throw an `Exception`. In this case,
55 * the stream will emit an `error` event and then [`close()`](#close-1) the stream.
56 *
57 * ```php
58 * $through = new ThroughStream(function ($data) {
59 * if (!is_string($data)) {
60 * throw new \UnexpectedValueException('Only strings allowed');
61 * }
62 * return $data;
63 * });
64 * $through->on('error', $this->expectCallableOnce()));
65 * $through->on('close', $this->expectCallableOnce()));
66 * $through->on('data', $this->expectCallableNever()));
67 *
68 * $through->write(2);
69 * ```
70 *
71 * @see WritableStreamInterface::write()
72 * @see WritableStreamInterface::end()
73 * @see DuplexStreamInterface::close()
74 * @see WritableStreamInterface::pipe()
75 */
76 final class ThroughStream extends EventEmitter implements DuplexStreamInterface
77 {
78 private $readable = true;
79 private $writable = true;
80 private $closed = false;
81 private $paused = false;
82 private $drain = false;
83 private $callback;
84
85 public function __construct($callback = null)
86 {
87 if ($callback !== null && !\is_callable($callback)) {
88 throw new InvalidArgumentException('Invalid transformation callback given');
89 }
90
91 $this->callback = $callback;
92 }
93
94 public function pause()
95 {
96 // only allow pause if still readable, false otherwise
97 $this->paused = $this->readable;
98 }
99
100 public function resume()
101 {
102 $this->paused = false;
103
104 // emit drain event if previous write was paused (throttled)
105 if ($this->drain) {
106 $this->drain = false;
107 $this->emit('drain');
108 }
109 }
110
111 public function pipe(WritableStreamInterface $dest, array $options = array())
112 {
113 return Util::pipe($this, $dest, $options);
114 }
115
116 public function isReadable()
117 {
118 return $this->readable;
119 }
120
121 public function isWritable()
122 {
123 return $this->writable;
124 }
125
126 public function write($data)
127 {
128 if (!$this->writable) {
129 return false;
130 }
131
132 if ($this->callback !== null) {
133 try {
134 $data = \call_user_func($this->callback, $data);
135 } catch (\Exception $e) {
136 $this->emit('error', array($e));
137 $this->close();
138
139 return false;
140 }
141 }
142
143 $this->emit('data', array($data));
144
145 // emit drain event on next resume if currently paused (throttled)
146 if ($this->paused) {
147 $this->drain = true;
148 }
149
150 // continue writing if still writable and not paused (throttled), false otherwise
151 return $this->writable && !$this->paused;
152 }
153
154 public function end($data = null)
155 {
156 if (!$this->writable) {
157 return;
158 }
159
160 if (null !== $data) {
161 $this->write($data);
162
163 // return if write() already caused the stream to close
164 if (!$this->writable) {
165 return;
166 }
167 }
168
169 $this->readable = false;
170 $this->writable = false;
171 $this->paused = false;
172 $this->drain = false;
173
174 $this->emit('end');
175 $this->close();
176 }
177
178 public function close()
179 {
180 if ($this->closed) {
181 return;
182 }
183
184 $this->readable = false;
185 $this->writable = false;
186 $this->paused = false;
187 $this->drain = false;
188
189 $this->closed = true;
190 $this->callback = null;
191
192 $this->emit('close');
193 $this->removeAllListeners();
194 }
195 }