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