give / vendor / stripe / stripe-php / lib / Collection.php

Collection.php in GiveWP – Donation Plugin and Fundraising Platform 4.16.9, at vendor/stripe/stripe-php/lib/Collection.php

313 lines 8.3 KB

Raw Download Zip

1	<?php
2
3	namespace Stripe;
4
5	/**
6	* Class Collection.
7	*
8	* @template TStripeObject of StripeObject
9	* @template-implements \IteratorAggregate<TStripeObject>
10	*
11	* @property string $object
12	* @property string $url
13	* @property bool $has_more
14	* @property TStripeObject[] $data
15	*/
16	class Collection extends StripeObject implements \Countable, \IteratorAggregate
17	{
18	const OBJECT_NAME = 'list';
19
20	use ApiOperations\Request;
21
22	/** @var array */
23	protected $filters = [];
24
25	/**
26	* @return string the base URL for the given class
27	*/
28	public static function baseUrl()
29	{
30	return Stripe::$apiBase;
31	}
32
33	/**
34	* Returns the filters.
35	*
36	* @return array the filters
37	*/
38	public function getFilters()
39	{
40	return $this->filters;
41	}
42
43	/**
44	* Sets the filters, removing paging options.
45	*
46	* @param array $filters the filters
47	*/
48	public function setFilters($filters)
49	{
50	$this->filters = $filters;
51	}
52
53	#[\ReturnTypeWillChange]
54	public function offsetGet($k)
55	{
56	if (\is_string($k)) {
57	return parent::offsetGet($k);
58	}
59	$msg = "You tried to access the {$k} index, but Collection " .
60	'types only support string keys. (HINT: List calls ' .
61	'return an object with a `data` (which is the data ' .
62	"array). You likely want to call ->data[{$k}])";
63
64	throw new Exception\InvalidArgumentException($msg);
65	}
66
67	/**
68	* @param null\|array $params
69	* @param null\|array\|string $opts
70	*
71	* @throws Exception\ApiErrorException
72	*
73	* @return Collection<TStripeObject>
74	*/
75	public function all($params = null, $opts = null)
76	{
77	self::_validateParams($params);
78	list($url, $params) = $this->extractPathAndUpdateParams($params);
79
80	list($response, $opts) = $this->_request('get', $url, $params, $opts);
81	$obj = Util\Util::convertToStripeObject($response, $opts);
82	if (!($obj instanceof \Stripe\Collection)) {
83	throw new \Stripe\Exception\UnexpectedValueException(
84	'Expected type ' . \Stripe\Collection::class . ', got "' . \get_class($obj) . '" instead.'
85	);
86	}
87	$obj->setFilters($params);
88
89	return $obj;
90	}
91
92	/**
93	* @param null\|array $params
94	* @param null\|array\|string $opts
95	*
96	* @throws Exception\ApiErrorException
97	*
98	* @return TStripeObject
99	*/
100	public function create($params = null, $opts = null)
101	{
102	self::_validateParams($params);
103	list($url, $params) = $this->extractPathAndUpdateParams($params);
104
105	list($response, $opts) = $this->_request('post', $url, $params, $opts);
106
107	return Util\Util::convertToStripeObject($response, $opts);
108	}
109
110	/**
111	* @param string $id
112	* @param null\|array $params
113	* @param null\|array\|string $opts
114	*
115	* @throws Exception\ApiErrorException
116	*
117	* @return TStripeObject
118	*/
119	public function retrieve($id, $params = null, $opts = null)
120	{
121	self::_validateParams($params);
122	list($url, $params) = $this->extractPathAndUpdateParams($params);
123
124	$id = Util\Util::utf8($id);
125	$extn = \urlencode($id);
126	list($response, $opts) = $this->_request(
127	'get',
128	"{$url}/{$extn}",
129	$params,
130	$opts
131	);
132
133	return Util\Util::convertToStripeObject($response, $opts);
134	}
135
136	/**
137	* @return int the number of objects in the current page
138	*/
139	#[\ReturnTypeWillChange]
140	public function count()
141	{
142	return \count($this->data);
143	}
144
145	/**
146	* @return \ArrayIterator an iterator that can be used to iterate
147	* across objects in the current page
148	*/
149	#[\ReturnTypeWillChange]
150	public function getIterator()
151	{
152	return new \ArrayIterator($this->data);
153	}
154
155	/**
156	* @return \ArrayIterator an iterator that can be used to iterate
157	* backwards across objects in the current page
158	*/
159	public function getReverseIterator()
160	{
161	return new \ArrayIterator(\array_reverse($this->data));
162	}
163
164	/**
165	* @return \Generator\|TStripeObject[] A generator that can be used to
166	* iterate across all objects across all pages. As page boundaries are
167	* encountered, the next page will be fetched automatically for
168	* continued iteration.
169	*/
170	public function autoPagingIterator()
171	{
172	$page = $this;
173
174	while (true) {
175	$filters = $this->filters ?: [];
176	if (\array_key_exists('ending_before', $filters)
177	&& !\array_key_exists('starting_after', $filters)) {
178	foreach ($page->getReverseIterator() as $item) {
179	yield $item;
180	}
181	$page = $page->previousPage();
182	} else {
183	foreach ($page as $item) {
184	yield $item;
185	}
186	$page = $page->nextPage();
187	}
188
189	if ($page->isEmpty()) {
190	break;
191	}
192	}
193	}
194
195	/**
196	* Returns an empty collection. This is returned from {@see nextPage()}
197	* when we know that there isn't a next page in order to replicate the
198	* behavior of the API when it attempts to return a page beyond the last.
199	*
200	* @param null\|array\|string $opts
201	*
202	* @return Collection
203	*/
204	public static function emptyCollection($opts = null)
205	{
206	return Collection::constructFrom(['data' => []], $opts);
207	}
208
209	/**
210	* Returns true if the page object contains no element.
211	*
212	* @return bool
213	*/
214	public function isEmpty()
215	{
216	return empty($this->data);
217	}
218
219	/**
220	* Fetches the next page in the resource list (if there is one).
221	*
222	* This method will try to respect the limit of the current page. If none
223	* was given, the default limit will be fetched again.
224	*
225	* @param null\|array $params
226	* @param null\|array\|string $opts
227	*
228	* @return Collection<TStripeObject>
229	*/
230	public function nextPage($params = null, $opts = null)
231	{
232	if (!$this->has_more) {
233	return static::emptyCollection($opts);
234	}
235
236	$lastId = \end($this->data)->id;
237
238	$params = \array_merge(
239	$this->filters ?: [],
240	['starting_after' => $lastId],
241	$params ?: []
242	);
243
244	return $this->all($params, $opts);
245	}
246
247	/**
248	* Fetches the previous page in the resource list (if there is one).
249	*
250	* This method will try to respect the limit of the current page. If none
251	* was given, the default limit will be fetched again.
252	*
253	* @param null\|array $params
254	* @param null\|array\|string $opts
255	*
256	* @return Collection<TStripeObject>
257	*/
258	public function previousPage($params = null, $opts = null)
259	{
260	if (!$this->has_more) {
261	return static::emptyCollection($opts);
262	}
263
264	$firstId = $this->data[0]->id;
265
266	$params = \array_merge(
267	$this->filters ?: [],
268	['ending_before' => $firstId],
269	$params ?: []
270	);
271
272	return $this->all($params, $opts);
273	}
274
275	/**
276	* Gets the first item from the current page. Returns `null` if the current page is empty.
277	*
278	* @return null\|TStripeObject
279	*/
280	public function first()
281	{
282	return \count($this->data) > 0 ? $this->data[0] : null;
283	}
284
285	/**
286	* Gets the last item from the current page. Returns `null` if the current page is empty.
287	*
288	* @return null\|TStripeObject
289	*/
290	public function last()
291	{
292	return \count($this->data) > 0 ? $this->data[\count($this->data) - 1] : null;
293	}
294
295	private function extractPathAndUpdateParams($params)
296	{
297	$url = \parse_url($this->url);
298	if (!isset($url['path'])) {
299	throw new Exception\UnexpectedValueException("Could not parse list url into parts: {$url}");
300	}
301
302	if (isset($url['query'])) {
303	// If the URL contains a query param, parse it out into $params so they
304	// don't interact weirdly with each other.
305	$query = [];
306	\parse_str($url['query'], $query);
307	$params = \array_merge($params ?: [], $query);
308	}
309
310	return [$url['path'], $params];
311	}
312	}
313