stockpack / vendor / guzzlehttp / promises / src / functions.php

functions.php in StockPack – Stock photos and AI images from Unsplash, Adobe Stock, Freepik and more 2.5.4, at vendor/guzzlehttp/promises/src/functions.php

472 lines 12.4 KB

Raw Download Zip

1	<?php
2	namespace GuzzleHttp\Promise;
3
4	/**
5	* Get the global task queue used for promise resolution.
6	*
7	* This task queue MUST be run in an event loop in order for promises to be
8	* settled asynchronously. It will be automatically run when synchronously
9	* waiting on a promise.
10	*
11	* <code>
12	* while ($eventLoop->isRunning()) {
13	* GuzzleHttp\Promise\queue()->run();
14	* }
15	* </code>
16	*
17	* @param TaskQueueInterface $assign Optionally specify a new queue instance.
18	*
19	* @return TaskQueueInterface
20	*/
21	function queue(TaskQueueInterface $assign = null)
22	{
23	static $queue;
24
25	if ($assign) {
26	$queue = $assign;
27	} elseif (!$queue) {
28	$queue = new TaskQueue();
29	}
30
31	return $queue;
32	}
33
34	/**
35	* Adds a function to run in the task queue when it is next `run()` and returns
36	* a promise that is fulfilled or rejected with the result.
37	*
38	* @param callable $task Task function to run.
39	*
40	* @return PromiseInterface
41	*/
42	function task(callable $task)
43	{
44	$queue = queue();
45	$promise = new Promise([$queue, 'run']);
46	$queue->add(function () use ($task, $promise) {
47	try {
48	$promise->resolve($task());
49	} catch (\Throwable $e) {
50	$promise->reject($e);
51	} catch (\Exception $e) {
52	$promise->reject($e);
53	}
54	});
55
56	return $promise;
57	}
58
59	/**
60	* Creates a promise for a value if the value is not a promise.
61	*
62	* @param mixed $value Promise or value.
63	*
64	* @return PromiseInterface
65	*/
66	function promise_for($value)
67	{
68	if ($value instanceof PromiseInterface) {
69	return $value;
70	}
71
72	// Return a Guzzle promise that shadows the given promise.
73	if (method_exists($value, 'then')) {
74	$wfn = method_exists($value, 'wait') ? [$value, 'wait'] : null;
75	$cfn = method_exists($value, 'cancel') ? [$value, 'cancel'] : null;
76	$promise = new Promise($wfn, $cfn);
77	$value->then([$promise, 'resolve'], [$promise, 'reject']);
78	return $promise;
79	}
80
81	return new FulfilledPromise($value);
82	}
83
84	/**
85	* Creates a rejected promise for a reason if the reason is not a promise. If
86	* the provided reason is a promise, then it is returned as-is.
87	*
88	* @param mixed $reason Promise or reason.
89	*
90	* @return PromiseInterface
91	*/
92	function rejection_for($reason)
93	{
94	if ($reason instanceof PromiseInterface) {
95	return $reason;
96	}
97
98	return new RejectedPromise($reason);
99	}
100
101	/**
102	* Create an exception for a rejected promise value.
103	*
104	* @param mixed $reason
105	*
106	* @return \Exception\|\Throwable
107	*/
108	function exception_for($reason)
109	{
110	return $reason instanceof \Exception \|\| $reason instanceof \Throwable
111	? $reason
112	: new RejectionException($reason);
113	}
114
115	/**
116	* Returns an iterator for the given value.
117	*
118	* @param mixed $value
119	*
120	* @return \Iterator
121	*/
122	function iter_for($value)
123	{
124	if ($value instanceof \Iterator) {
125	return $value;
126	} elseif (is_array($value)) {
127	return new \ArrayIterator($value);
128	} else {
129	return new \ArrayIterator([$value]);
130	}
131	}
132
133	/**
134	* Synchronously waits on a promise to resolve and returns an inspection state
135	* array.
136	*
137	* Returns a state associative array containing a "state" key mapping to a
138	* valid promise state. If the state of the promise is "fulfilled", the array
139	* will contain a "value" key mapping to the fulfilled value of the promise. If
140	* the promise is rejected, the array will contain a "reason" key mapping to
141	* the rejection reason of the promise.
142	*
143	* @param PromiseInterface $promise Promise or value.
144	*
145	* @return array
146	*/
147	function inspect(PromiseInterface $promise)
148	{
149	try {
150	return [
151	'state' => PromiseInterface::FULFILLED,
152	'value' => $promise->wait()
153	];
154	} catch (RejectionException $e) {
155	return ['state' => PromiseInterface::REJECTED, 'reason' => $e->getReason()];
156	} catch (\Throwable $e) {
157	return ['state' => PromiseInterface::REJECTED, 'reason' => $e];
158	} catch (\Exception $e) {
159	return ['state' => PromiseInterface::REJECTED, 'reason' => $e];
160	}
161	}
162
163	/**
164	* Waits on all of the provided promises, but does not unwrap rejected promises
165	* as thrown exception.
166	*
167	* Returns an array of inspection state arrays.
168	*
169	* @param PromiseInterface[] $promises Traversable of promises to wait upon.
170	*
171	* @return array
172	* @see GuzzleHttp\Promise\inspect for the inspection state array format.
173	*/
174	function inspect_all($promises)
175	{
176	$results = [];
177	foreach ($promises as $key => $promise) {
178	$results[$key] = inspect($promise);
179	}
180
181	return $results;
182	}
183
184	/**
185	* Waits on all of the provided promises and returns the fulfilled values.
186	*
187	* Returns an array that contains the value of each promise (in the same order
188	* the promises were provided). An exception is thrown if any of the promises
189	* are rejected.
190	*
191	* @param mixed $promises Iterable of PromiseInterface objects to wait on.
192	*
193	* @return array
194	* @throws \Exception on error
195	* @throws \Throwable on error in PHP >=7
196	*/
197	function unwrap($promises)
198	{
199	$results = [];
200	foreach ($promises as $key => $promise) {
201	$results[$key] = $promise->wait();
202	}
203
204	return $results;
205	}
206
207	/**
208	* Given an array of promises, return a promise that is fulfilled when all the
209	* items in the array are fulfilled.
210	*
211	* The promise's fulfillment value is an array with fulfillment values at
212	* respective positions to the original array. If any promise in the array
213	* rejects, the returned promise is rejected with the rejection reason.
214	*
215	* @param mixed $promises Promises or values.
216	* @param bool $recursive - If true, resolves new promises that might have been added to the stack during its own resolution.
217	*
218	* @return PromiseInterface
219	*/
220	function all($promises, $recursive = false)
221	{
222	$results = [];
223	$promise = \GuzzleHttp\Promise\each(
224	$promises,
225	function ($value, $idx) use (&$results) {
226	$results[$idx] = $value;
227	},
228	function ($reason, $idx, Promise $aggregate) {
229	$aggregate->reject($reason);
230	}
231	)->then(function () use (&$results) {
232	ksort($results);
233	return $results;
234	});
235
236	if (true === $recursive) {
237	$promise = $promise->then(function ($results) use ($recursive, &$promises) {
238	foreach ($promises AS $promise) {
239	if (\GuzzleHttp\Promise\PromiseInterface::PENDING === $promise->getState()) {
240	return all($promises, $recursive);
241	}
242	}
243	return $results;
244	});
245	}
246
247	return $promise;
248	}
249
250	/**
251	* Initiate a competitive race between multiple promises or values (values will
252	* become immediately fulfilled promises).
253	*
254	* When count amount of promises have been fulfilled, the returned promise is
255	* fulfilled with an array that contains the fulfillment values of the winners
256	* in order of resolution.
257	*
258	* This promise is rejected with a {@see GuzzleHttp\Promise\AggregateException}
259	* if the number of fulfilled promises is less than the desired $count.
260	*
261	* @param int $count Total number of promises.
262	* @param mixed $promises Promises or values.
263	*
264	* @return PromiseInterface
265	*/
266	function some($count, $promises)
267	{
268	$results = [];
269	$rejections = [];
270
271	return \GuzzleHttp\Promise\each(
272	$promises,
273	function ($value, $idx, PromiseInterface $p) use (&$results, $count) {
274	if ($p->getState() !== PromiseInterface::PENDING) {
275	return;
276	}
277	$results[$idx] = $value;
278	if (count($results) >= $count) {
279	$p->resolve(null);
280	}
281	},
282	function ($reason) use (&$rejections) {
283	$rejections[] = $reason;
284	}
285	)->then(
286	function () use (&$results, &$rejections, $count) {
287	if (count($results) !== $count) {
288	throw new AggregateException(
289	'Not enough promises to fulfill count',
290	$rejections
291	);
292	}
293	ksort($results);
294	return array_values($results);
295	}
296	);
297	}
298
299	/**
300	* Like some(), with 1 as count. However, if the promise fulfills, the
301	* fulfillment value is not an array of 1 but the value directly.
302	*
303	* @param mixed $promises Promises or values.
304	*
305	* @return PromiseInterface
306	*/
307	function any($promises)
308	{
309	return some(1, $promises)->then(function ($values) { return $values[0]; });
310	}
311
312	/**
313	* Returns a promise that is fulfilled when all of the provided promises have
314	* been fulfilled or rejected.
315	*
316	* The returned promise is fulfilled with an array of inspection state arrays.
317	*
318	* @param mixed $promises Promises or values.
319	*
320	* @return PromiseInterface
321	* @see GuzzleHttp\Promise\inspect for the inspection state array format.
322	*/
323	function settle($promises)
324	{
325	$results = [];
326
327	return \GuzzleHttp\Promise\each(
328	$promises,
329	function ($value, $idx) use (&$results) {
330	$results[$idx] = ['state' => PromiseInterface::FULFILLED, 'value' => $value];
331	},
332	function ($reason, $idx) use (&$results) {
333	$results[$idx] = ['state' => PromiseInterface::REJECTED, 'reason' => $reason];
334	}
335	)->then(function () use (&$results) {
336	ksort($results);
337	return $results;
338	});
339	}
340
341	/**
342	* Given an iterator that yields promises or values, returns a promise that is
343	* fulfilled with a null value when the iterator has been consumed or the
344	* aggregate promise has been fulfilled or rejected.
345	*
346	* $onFulfilled is a function that accepts the fulfilled value, iterator
347	* index, and the aggregate promise. The callback can invoke any necessary side
348	* effects and choose to resolve or reject the aggregate promise if needed.
349	*
350	* $onRejected is a function that accepts the rejection reason, iterator
351	* index, and the aggregate promise. The callback can invoke any necessary side
352	* effects and choose to resolve or reject the aggregate promise if needed.
353	*
354	* @param mixed $iterable Iterator or array to iterate over.
355	* @param callable $onFulfilled
356	* @param callable $onRejected
357	*
358	* @return PromiseInterface
359	*/
360	function each(
361	$iterable,
362	callable $onFulfilled = null,
363	callable $onRejected = null
364	) {
365	return (new EachPromise($iterable, [
366	'fulfilled' => $onFulfilled,
367	'rejected' => $onRejected
368	]))->promise();
369	}
370
371	/**
372	* Like each, but only allows a certain number of outstanding promises at any
373	* given time.
374	*
375	* $concurrency may be an integer or a function that accepts the number of
376	* pending promises and returns a numeric concurrency limit value to allow for
377	* dynamic a concurrency size.
378	*
379	* @param mixed $iterable
380	* @param int\|callable $concurrency
381	* @param callable $onFulfilled
382	* @param callable $onRejected
383	*
384	* @return PromiseInterface
385	*/
386	function each_limit(
387	$iterable,
388	$concurrency,
389	callable $onFulfilled = null,
390	callable $onRejected = null
391	) {
392	return (new EachPromise($iterable, [
393	'fulfilled' => $onFulfilled,
394	'rejected' => $onRejected,
395	'concurrency' => $concurrency
396	]))->promise();
397	}
398
399	/**
400	* Like each_limit, but ensures that no promise in the given $iterable argument
401	* is rejected. If any promise is rejected, then the aggregate promise is
402	* rejected with the encountered rejection.
403	*
404	* @param mixed $iterable
405	* @param int\|callable $concurrency
406	* @param callable $onFulfilled
407	*
408	* @return PromiseInterface
409	*/
410	function each_limit_all(
411	$iterable,
412	$concurrency,
413	callable $onFulfilled = null
414	) {
415	return each_limit(
416	$iterable,
417	$concurrency,
418	$onFulfilled,
419	function ($reason, $idx, PromiseInterface $aggregate) {
420	$aggregate->reject($reason);
421	}
422	);
423	}
424
425	/**
426	* Returns true if a promise is fulfilled.
427	*
428	* @param PromiseInterface $promise
429	*
430	* @return bool
431	*/
432	function is_fulfilled(PromiseInterface $promise)
433	{
434	return $promise->getState() === PromiseInterface::FULFILLED;
435	}
436
437	/**
438	* Returns true if a promise is rejected.
439	*
440	* @param PromiseInterface $promise
441	*
442	* @return bool
443	*/
444	function is_rejected(PromiseInterface $promise)
445	{
446	return $promise->getState() === PromiseInterface::REJECTED;
447	}
448
449	/**
450	* Returns true if a promise is fulfilled or rejected.
451	*
452	* @param PromiseInterface $promise
453	*
454	* @return bool
455	*/
456	function is_settled(PromiseInterface $promise)
457	{
458	return $promise->getState() !== PromiseInterface::PENDING;
459	}
460
461	/**
462	* @see Coroutine
463	*
464	* @param callable $generatorFn
465	*
466	* @return PromiseInterface
467	*/
468	function coroutine(callable $generatorFn)
469	{
470	return new Coroutine($generatorFn);
471	}
472