mantis-matrix-integration – Blame information for rev 1

Subversion Repositories:
Rev:
Rev Author Line No. Line
1 office 1 <?php
2  
3 namespace GuzzleHttp;
4  
5 use GuzzleHttp\Promise\PromiseInterface;
6 use Psr\Http\Message\RequestInterface;
7 use Psr\Http\Message\ResponseInterface;
8  
9 /**
10 * Creates a composed Guzzle handler function by stacking middlewares on top of
11 * an HTTP handler function.
12 *
13 * @final
14 */
15 class HandlerStack
16 {
17 /**
18 * @var (callable(RequestInterface, array): PromiseInterface)|null
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 (callable(RequestInterface, array): PromiseInterface)|null
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 (callable(RequestInterface, array): PromiseInterface)|null $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 (callable(RequestInterface, array): PromiseInterface)|null $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 if (!is_string($remove) && !is_callable($remove)) {
184 trigger_deprecation('guzzlehttp/guzzle', '7.4', 'Not passing a callable or string to %s::%s() is deprecated and will cause an error in 8.0.', __CLASS__, __FUNCTION__);
185 }
186  
187 $this->cached = null;
188 $idx = \is_callable($remove) ? 0 : 1;
189 $this->stack = \array_values(\array_filter(
190 $this->stack,
191 static function ($tuple) use ($idx, $remove) {
192 return $tuple[$idx] !== $remove;
193 }
194 ));
195 }
196  
197 /**
198 * Compose the middleware and handler into a single callable function.
199 *
200 * @return callable(RequestInterface, array): PromiseInterface
201 */
202 public function resolve(): callable
203 {
204 if ($this->cached === null) {
205 if (($prev = $this->handler) === null) {
206 throw new \LogicException('No handler has been specified');
207 }
208  
209 foreach (\array_reverse($this->stack) as $fn) {
210 /** @var callable(RequestInterface, array): PromiseInterface $prev */
211 $prev = $fn[0]($prev);
212 }
213  
214 $this->cached = $prev;
215 }
216  
217 return $this->cached;
218 }
219  
220 private function findByName(string $name): int
221 {
222 foreach ($this->stack as $k => $v) {
223 if ($v[1] === $name) {
224 return $k;
225 }
226 }
227  
228 throw new \InvalidArgumentException("Middleware not found: $name");
229 }
230  
231 /**
232 * Splices a function into the middleware list at a specific position.
233 */
234 private function splice(string $findName, string $withName, callable $middleware, bool $before): void
235 {
236 $this->cached = null;
237 $idx = $this->findByName($findName);
238 $tuple = [$middleware, $withName];
239  
240 if ($before) {
241 if ($idx === 0) {
242 \array_unshift($this->stack, $tuple);
243 } else {
244 $replacement = [$tuple, $this->stack[$idx]];
245 \array_splice($this->stack, $idx, 1, $replacement);
246 }
247 } elseif ($idx === \count($this->stack) - 1) {
248 $this->stack[] = $tuple;
249 } else {
250 $replacement = [$this->stack[$idx], $tuple];
251 \array_splice($this->stack, $idx, 1, $replacement);
252 }
253 }
254  
255 /**
256 * Provides a debug string for a given callable.
257 *
258 * @param callable|string $fn Function to write as a string.
259 */
260 private function debugCallable($fn): string
261 {
262 if (\is_string($fn)) {
263 return "callable({$fn})";
264 }
265  
266 if (\is_array($fn)) {
267 return \is_string($fn[0])
268 ? "callable({$fn[0]}::{$fn[1]})"
269 : "callable(['".\get_class($fn[0])."', '{$fn[1]}'])";
270 }
271  
272 /** @var object $fn */
273 return 'callable('.\spl_object_hash($fn).')';
274 }
275 }