annotate vendor/guzzlehttp/guzzle/src/HandlerStack.php @ 19:fa3358dc1485 tip

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