1 | <?php |
||
15 | class HandlerStack |
||
16 | { |
||
17 | /** |
||
18 | * @var null|callable(RequestInterface, array): PromiseInterface |
||
19 | */ |
||
20 | private $handler; |
||
21 | |||
22 | /** |
||
23 | * @var array{(callable(callable(RequestInterface, array): PromiseInterface): callable), (string|null)}[] |
||
24 | */ |
||
25 | private $stack = []; |
||
26 | |||
27 | /** |
||
28 | * @var null|callable(RequestInterface, array): PromiseInterface |
||
29 | */ |
||
30 | private $cached; |
||
31 | |||
32 | /** |
||
33 | * Creates a default handler stack that can be used by clients. |
||
34 | * |
||
35 | * The returned handler will wrap the provided handler or use the most |
||
36 | * appropriate default handler for your system. The returned HandlerStack has |
||
37 | * support for cookies, redirects, HTTP error exceptions, and preparing a body |
||
38 | * before sending. |
||
39 | * |
||
40 | * The returned handler stack can be passed to a client in the "handler" |
||
41 | * option. |
||
42 | * |
||
43 | * @param null|callable(RequestInterface, array): PromiseInterface $handler HTTP handler function to use with the stack. If no |
||
44 | * handler is provided, the best handler for your |
||
45 | * system will be utilized. |
||
46 | */ |
||
47 | public static function create(?callable $handler = null): self |
||
48 | { |
||
49 | $stack = new self($handler ?: Utils::chooseHandler()); |
||
50 | $stack->push(Middleware::httpErrors(), 'http_errors'); |
||
51 | $stack->push(Middleware::redirect(), 'allow_redirects'); |
||
52 | $stack->push(Middleware::cookies(), 'cookies'); |
||
53 | $stack->push(Middleware::prepareBody(), 'prepare_body'); |
||
54 | |||
55 | return $stack; |
||
56 | } |
||
57 | |||
58 | /** |
||
59 | * @param null|callable(RequestInterface, array): PromiseInterface $handler Underlying HTTP handler. |
||
60 | */ |
||
61 | public function __construct(callable $handler = null) |
||
62 | { |
||
63 | $this->handler = $handler; |
||
64 | } |
||
65 | |||
66 | /** |
||
67 | * Invokes the handler stack as a composed handler |
||
68 | * |
||
69 | * @return ResponseInterface|PromiseInterface |
||
70 | */ |
||
71 | public function __invoke(RequestInterface $request, array $options) |
||
72 | { |
||
73 | $handler = $this->resolve(); |
||
74 | |||
75 | return $handler($request, $options); |
||
76 | } |
||
77 | |||
78 | /** |
||
79 | * Dumps a string representation of the stack. |
||
80 | * |
||
81 | * @return string |
||
82 | */ |
||
83 | public function __toString() |
||
84 | { |
||
85 | $depth = 0; |
||
86 | $stack = []; |
||
87 | |||
88 | if ($this->handler !== null) { |
||
89 | $stack[] = "0) Handler: " . $this->debugCallable($this->handler); |
||
90 | } |
||
91 | |||
92 | $result = ''; |
||
93 | foreach (\array_reverse($this->stack) as $tuple) { |
||
94 | $depth++; |
||
95 | $str = "{$depth}) Name: '{$tuple[1]}', "; |
||
96 | $str .= "Function: " . $this->debugCallable($tuple[0]); |
||
97 | $result = "> {$str}\n{$result}"; |
||
98 | $stack[] = $str; |
||
99 | } |
||
100 | |||
101 | foreach (\array_keys($stack) as $k) { |
||
102 | $result .= "< {$stack[$k]}\n"; |
||
103 | } |
||
104 | |||
105 | return $result; |
||
106 | } |
||
107 | |||
108 | /** |
||
109 | * Set the HTTP handler that actually returns a promise. |
||
110 | * |
||
111 | * @param callable(RequestInterface, array): PromiseInterface $handler Accepts a request and array of options and |
||
112 | * returns a Promise. |
||
113 | */ |
||
114 | public function setHandler(callable $handler): void |
||
115 | { |
||
116 | $this->handler = $handler; |
||
117 | $this->cached = null; |
||
118 | } |
||
119 | |||
120 | /** |
||
121 | * Returns true if the builder has a handler. |
||
122 | */ |
||
123 | public function hasHandler(): bool |
||
124 | { |
||
125 | return $this->handler !== null ; |
||
126 | } |
||
127 | |||
128 | /** |
||
129 | * Unshift a middleware to the bottom of the stack. |
||
130 | * |
||
131 | * @param callable(callable): callable $middleware Middleware function |
||
132 | * @param string $name Name to register for this middleware. |
||
133 | */ |
||
134 | public function unshift(callable $middleware, ?string $name = null): void |
||
135 | { |
||
136 | \array_unshift($this->stack, [$middleware, $name]); |
||
137 | $this->cached = null; |
||
138 | } |
||
139 | |||
140 | /** |
||
141 | * Push a middleware to the top of the stack. |
||
142 | * |
||
143 | * @param callable(callable): callable $middleware Middleware function |
||
144 | * @param string $name Name to register for this middleware. |
||
145 | */ |
||
146 | public function push(callable $middleware, string $name = ''): void |
||
147 | { |
||
148 | $this->stack[] = [$middleware, $name]; |
||
149 | $this->cached = null; |
||
150 | } |
||
151 | |||
152 | /** |
||
153 | * Add a middleware before another middleware by name. |
||
154 | * |
||
155 | * @param string $findName Middleware to find |
||
156 | * @param callable(callable): callable $middleware Middleware function |
||
157 | * @param string $withName Name to register for this middleware. |
||
158 | */ |
||
159 | public function before(string $findName, callable $middleware, string $withName = ''): void |
||
160 | { |
||
161 | $this->splice($findName, $withName, $middleware, true); |
||
162 | } |
||
163 | |||
164 | /** |
||
165 | * Add a middleware after another middleware by name. |
||
166 | * |
||
167 | * @param string $findName Middleware to find |
||
168 | * @param callable(callable): callable $middleware Middleware function |
||
169 | * @param string $withName Name to register for this middleware. |
||
170 | */ |
||
171 | public function after(string $findName, callable $middleware, string $withName = ''): void |
||
172 | { |
||
173 | $this->splice($findName, $withName, $middleware, false); |
||
174 | } |
||
175 | |||
176 | /** |
||
177 | * Remove a middleware by instance or name from the stack. |
||
178 | * |
||
179 | * @param callable|string $remove Middleware to remove by instance or name. |
||
180 | */ |
||
181 | public function remove($remove): void |
||
182 | { |
||
183 | $this->cached = null; |
||
184 | $idx = \is_callable($remove) ? 0 : 1; |
||
185 | $this->stack = \array_values(\array_filter( |
||
186 | $this->stack, |
||
187 | static function ($tuple) use ($idx, $remove) { |
||
188 | return $tuple[$idx] !== $remove; |
||
189 | } |
||
190 | )); |
||
191 | } |
||
192 | |||
193 | /** |
||
194 | * Compose the middleware and handler into a single callable function. |
||
195 | * |
||
196 | * @return callable(RequestInterface, array): PromiseInterface |
||
|
|||
197 | */ |
||
198 | public function resolve(): callable |
||
199 | { |
||
200 | if ($this->cached === null) { |
||
201 | if (($prev = $this->handler) === null) { |
||
202 | throw new \LogicException('No handler has been specified'); |
||
203 | } |
||
204 | |||
205 | foreach (\array_reverse($this->stack) as $fn) { |
||
206 | /** @var callable(RequestInterface, array): PromiseInterface $prev */ |
||
207 | $prev = $fn[0]($prev); |
||
208 | } |
||
209 | |||
210 | $this->cached = $prev; |
||
211 | } |
||
212 | |||
213 | return $this->cached; |
||
214 | } |
||
215 | |||
216 | private function findByName(string $name): int |
||
226 | |||
227 | /** |
||
228 | * Splices a function into the middleware list at a specific position. |
||
229 | */ |
||
230 | private function splice(string $findName, string $withName, callable $middleware, bool $before): void |
||
231 | { |
||
232 | $this->cached = null; |
||
233 | $idx = $this->findByName($findName); |
||
234 | $tuple = [$middleware, $withName]; |
||
235 | |||
236 | if ($before) { |
||
237 | if ($idx === 0) { |
||
238 | \array_unshift($this->stack, $tuple); |
||
250 | |||
251 | /** |
||
252 | * Provides a debug string for a given callable. |
||
253 | * |
||
254 | * @param callable $fn Function to write as a string. |
||
255 | */ |
||
256 | private function debugCallable($fn): string |
||
271 | } |
||
272 |
This check marks PHPDoc comments that could not be parsed by our parser. To see which comment annotations we can parse, please refer to our documentation on supported doc-types.