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