4 use Psr\Http\Message\RequestInterface;
7 * Creates a composed Guzzle handler function by stacking middlewares on top of
8 * an HTTP handler function.
18 /** @var callable|null */
22 * Creates a default handler stack that can be used by clients.
24 * The returned handler will wrap the provided handler or use the most
25 * appropriate default handler for you system. The returned HandlerStack has
26 * support for cookies, redirects, HTTP error exceptions, and preparing a body
29 * The returned handler stack can be passed to a client in the "handler"
32 * @param callable $handler HTTP handler function to use with the stack. If no
33 * handler is provided, the best handler for your
34 * system will be utilized.
36 * @return HandlerStack
38 public static function create(callable $handler = null)
40 $stack = new self($handler ?: choose_handler());
41 $stack->push(Middleware::httpErrors(), 'http_errors');
42 $stack->push(Middleware::redirect(), 'allow_redirects');
43 $stack->push(Middleware::cookies(), 'cookies');
44 $stack->push(Middleware::prepareBody(), 'prepare_body');
50 * @param callable $handler Underlying HTTP handler.
52 public function __construct(callable $handler = null)
54 $this->handler = $handler;
58 * Invokes the handler stack as a composed handler
60 * @param RequestInterface $request
61 * @param array $options
63 public function __invoke(RequestInterface $request, array $options)
65 $handler = $this->resolve();
67 return $handler($request, $options);
71 * Dumps a string representation of the stack.
75 public function __toString()
80 $stack[] = "0) Handler: " . $this->debugCallable($this->handler);
84 foreach (array_reverse($this->stack) as $tuple) {
86 $str = "{$depth}) Name: '{$tuple[1]}', ";
87 $str .= "Function: " . $this->debugCallable($tuple[0]);
88 $result = "> {$str}\n{$result}";
92 foreach (array_keys($stack) as $k) {
93 $result .= "< {$stack[$k]}\n";
100 * Set the HTTP handler that actually returns a promise.
102 * @param callable $handler Accepts a request and array of options and
105 public function setHandler(callable $handler)
107 $this->handler = $handler;
108 $this->cached = null;
112 * Returns true if the builder has a handler.
116 public function hasHandler()
118 return (bool) $this->handler;
122 * Unshift a middleware to the bottom of the stack.
124 * @param callable $middleware Middleware function
125 * @param string $name Name to register for this middleware.
127 public function unshift(callable $middleware, $name = null)
129 array_unshift($this->stack, [$middleware, $name]);
130 $this->cached = null;
134 * Push a middleware to the top of the stack.
136 * @param callable $middleware Middleware function
137 * @param string $name Name to register for this middleware.
139 public function push(callable $middleware, $name = '')
141 $this->stack[] = [$middleware, $name];
142 $this->cached = null;
146 * Add a middleware before another middleware by name.
148 * @param string $findName Middleware to find
149 * @param callable $middleware Middleware function
150 * @param string $withName Name to register for this middleware.
152 public function before($findName, callable $middleware, $withName = '')
154 $this->splice($findName, $withName, $middleware, true);
158 * Add a middleware after another middleware by name.
160 * @param string $findName Middleware to find
161 * @param callable $middleware Middleware function
162 * @param string $withName Name to register for this middleware.
164 public function after($findName, callable $middleware, $withName = '')
166 $this->splice($findName, $withName, $middleware, false);
170 * Remove a middleware by instance or name from the stack.
172 * @param callable|string $remove Middleware to remove by instance or name.
174 public function remove($remove)
176 $this->cached = null;
177 $idx = is_callable($remove) ? 0 : 1;
178 $this->stack = array_values(array_filter(
180 function ($tuple) use ($idx, $remove) {
181 return $tuple[$idx] !== $remove;
187 * Compose the middleware and handler into a single callable function.
191 public function resolve()
193 if (!$this->cached) {
194 if (!($prev = $this->handler)) {
195 throw new \LogicException('No handler has been specified');
198 foreach (array_reverse($this->stack) as $fn) {
199 $prev = $fn[0]($prev);
202 $this->cached = $prev;
205 return $this->cached;
212 private function findByName($name)
214 foreach ($this->stack as $k => $v) {
215 if ($v[1] === $name) {
220 throw new \InvalidArgumentException("Middleware not found: $name");
224 * Splices a function into the middleware list at a specific position.
228 * @param callable $middleware
231 private function splice($findName, $withName, callable $middleware, $before)
233 $this->cached = null;
234 $idx = $this->findByName($findName);
235 $tuple = [$middleware, $withName];
239 array_unshift($this->stack, $tuple);
241 $replacement = [$tuple, $this->stack[$idx]];
242 array_splice($this->stack, $idx, 1, $replacement);
244 } elseif ($idx === count($this->stack) - 1) {
245 $this->stack[] = $tuple;
247 $replacement = [$this->stack[$idx], $tuple];
248 array_splice($this->stack, $idx, 1, $replacement);
253 * Provides a debug string for a given callable.
255 * @param array|callable $fn Function to write as a string.
259 private function debugCallable($fn)
261 if (is_string($fn)) {
262 return "callable({$fn})";
266 return is_string($fn[0])
267 ? "callable({$fn[0]}::{$fn[1]})"
268 : "callable(['" . get_class($fn[0]) . "', '{$fn[1]}'])";
271 return 'callable(' . spl_object_hash($fn) . ')';