gmail-smtp / google-api-php-client / vendor / guzzlehttp / guzzle / src / HandlerStack.php

HandlerStack.php in Gmail SMTP trunk, at google-api-php-client/vendor/guzzlehttp/guzzle/src/HandlerStack.php

290 lines 8.9 KB

Raw Download Zip

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
189	if (\is_string($remove)) {
190	$count = \count($this->stack);
191	$this->stack = \array_values(\array_filter(
192	$this->stack,
193	static function ($tuple) use ($remove) {
194	return $tuple[1] !== $remove;
195	}
196	));
197
198	if ($count !== \count($this->stack) \|\| !\is_callable($remove)) {
199	return;
200	}
201	}
202
203	$this->stack = \array_values(\array_filter(
204	$this->stack,
205	static function ($tuple) use ($remove) {
206	return $tuple[0] !== $remove;
207	}
208	));
209	}
210
211	/**
212	* Compose the middleware and handler into a single callable function.
213	*
214	* @return callable(RequestInterface, array): PromiseInterface
215	*/
216	public function resolve(): callable
217	{
218	if ($this->cached === null) {
219	if (($prev = $this->handler) === null) {
220	throw new \LogicException('No handler has been specified');
221	}
222
223	foreach (\array_reverse($this->stack) as $fn) {
224	/** @var callable(RequestInterface, array): PromiseInterface $prev */
225	$prev = $fn[0]($prev);
226	}
227
228	$this->cached = $prev;
229	}
230
231	return $this->cached;
232	}
233
234	private function findByName(string $name): int
235	{
236	foreach ($this->stack as $k => $v) {
237	if ($v[1] === $name) {
238	return $k;
239	}
240	}
241
242	throw new \InvalidArgumentException("Middleware not found: $name");
243	}
244
245	/**
246	* Splices a function into the middleware list at a specific position.
247	*/
248	private function splice(string $findName, string $withName, callable $middleware, bool $before): void
249	{
250	$this->cached = null;
251	$idx = $this->findByName($findName);
252	$tuple = [$middleware, $withName];
253
254	if ($before) {
255	if ($idx === 0) {
256	\array_unshift($this->stack, $tuple);
257	} else {
258	$replacement = [$tuple, $this->stack[$idx]];
259	\array_splice($this->stack, $idx, 1, $replacement);
260	}
261	} elseif ($idx === \count($this->stack) - 1) {
262	$this->stack[] = $tuple;
263	} else {
264	$replacement = [$this->stack[$idx], $tuple];
265	\array_splice($this->stack, $idx, 1, $replacement);
266	}
267	}
268
269	/**
270	* Provides a debug string for a given callable.
271	*
272	* @param callable\|string $fn Function to write as a string.
273	*/
274	private function debugCallable($fn): string
275	{
276	if (\is_string($fn)) {
277	return "callable({$fn})";
278	}
279
280	if (\is_array($fn)) {
281	return \is_string($fn[0])
282	? "callable({$fn[0]}::{$fn[1]})"
283	: "callable(['".\get_class($fn[0])."', '{$fn[1]}'])";
284	}
285
286	/** @var object $fn */
287	return 'callable('.\spl_object_hash($fn).')';
288	}
289	}
290