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

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

235 lines 6.4 KB

Raw Download Zip

1	<?php
2
3	namespace Stripe;
4
5	/**
6	* Search results for an API resource.
7	*
8	* This behaves similarly to <code>Collection</code> in that they both wrap
9	* around a list of objects and provide pagination. However the
10	* <code>SearchResult</code> object paginates by relying on a
11	* <code>next_page</code> token included in the response rather than using
12	* object IDs and a <code>starting_before</code>/<code>ending_after</code>
13	* parameter. Thus, <code>SearchResult</code> only supports forwards pagination.
14	*
15	* The {@see $total_count} property is only available when
16	* the `expand` parameter contains `total_count`.
17	*
18	* @template TStripeObject of StripeObject
19	* @template-implements \IteratorAggregate<TStripeObject>
20	*
21	* @property string $object
22	* @property string $url
23	* @property string $next_page
24	* @property int $total_count
25	* @property bool $has_more
26	* @property TStripeObject[] $data
27	*/
28	class SearchResult extends StripeObject implements \Countable, \IteratorAggregate
29	{
30	const OBJECT_NAME = 'search_result';
31
32	use ApiOperations\Request;
33
34	/** @var array */
35	protected $filters = [];
36
37	/**
38	* @return string the base URL for the given class
39	*/
40	public static function baseUrl()
41	{
42	return Stripe::$apiBase;
43	}
44
45	/**
46	* Returns the filters.
47	*
48	* @return array the filters
49	*/
50	public function getFilters()
51	{
52	return $this->filters;
53	}
54
55	/**
56	* Sets the filters, removing paging options.
57	*
58	* @param array $filters the filters
59	*/
60	public function setFilters($filters)
61	{
62	$this->filters = $filters;
63	}
64
65	#[\ReturnTypeWillChange]
66	public function offsetGet($k)
67	{
68	if (\is_string($k)) {
69	return parent::offsetGet($k);
70	}
71	$msg = "You tried to access the {$k} index, but SearchResult " .
72	'types only support string keys. (HINT: Search calls ' .
73	'return an object with a `data` (which is the data ' .
74	"array). You likely want to call ->data[{$k}])";
75
76	throw new Exception\InvalidArgumentException($msg);
77	}
78
79	/**
80	* @param null\|array $params
81	* @param null\|array\|string $opts
82	*
83	* @throws Exception\ApiErrorException
84	*
85	* @return SearchResult<TStripeObject>
86	*/
87	public function all($params = null, $opts = null)
88	{
89	self::_validateParams($params);
90	list($url, $params) = $this->extractPathAndUpdateParams($params);
91
92	list($response, $opts) = $this->_request('get', $url, $params, $opts);
93	$obj = Util\Util::convertToStripeObject($response, $opts);
94	if (!($obj instanceof \Stripe\SearchResult)) {
95	throw new \Stripe\Exception\UnexpectedValueException(
96	'Expected type ' . \Stripe\SearchResult::class . ', got "' . \get_class($obj) . '" instead.'
97	);
98	}
99	$obj->setFilters($params);
100
101	return $obj;
102	}
103
104	/**
105	* @return int the number of objects in the current page
106	*/
107	#[\ReturnTypeWillChange]
108	public function count()
109	{
110	return \count($this->data);
111	}
112
113	/**
114	* @return \ArrayIterator an iterator that can be used to iterate
115	* across objects in the current page
116	*/
117	#[\ReturnTypeWillChange]
118	public function getIterator()
119	{
120	return new \ArrayIterator($this->data);
121	}
122
123	/**
124	* @return \Generator\|TStripeObject[] A generator that can be used to
125	* iterate across all objects across all pages. As page boundaries are
126	* encountered, the next page will be fetched automatically for
127	* continued iteration.
128	*/
129	public function autoPagingIterator()
130	{
131	$page = $this;
132
133	while (true) {
134	foreach ($page as $item) {
135	yield $item;
136	}
137	$page = $page->nextPage();
138
139	if ($page->isEmpty()) {
140	break;
141	}
142	}
143	}
144
145	/**
146	* Returns an empty set of search results. This is returned from
147	* {@see nextPage()} when we know that there isn't a next page in order to
148	* replicate the behavior of the API when it attempts to return a page
149	* beyond the last.
150	*
151	* @param null\|array\|string $opts
152	*
153	* @return SearchResult
154	*/
155	public static function emptySearchResult($opts = null)
156	{
157	return SearchResult::constructFrom(['data' => []], $opts);
158	}
159
160	/**
161	* Returns true if the page object contains no element.
162	*
163	* @return bool
164	*/
165	public function isEmpty()
166	{
167	return empty($this->data);
168	}
169
170	/**
171	* Fetches the next page in the resource list (if there is one).
172	*
173	* This method will try to respect the limit of the current page. If none
174	* was given, the default limit will be fetched again.
175	*
176	* @param null\|array $params
177	* @param null\|array\|string $opts
178	*
179	* @return SearchResult<TStripeObject>
180	*/
181	public function nextPage($params = null, $opts = null)
182	{
183	if (!$this->has_more) {
184	return static::emptySearchResult($opts);
185	}
186
187	$params = \array_merge(
188	$this->filters ?: [],
189	['page' => $this->next_page],
190	$params ?: []
191	);
192
193	return $this->all($params, $opts);
194	}
195
196	/**
197	* Gets the first item from the current page. Returns `null` if the current page is empty.
198	*
199	* @return null\|TStripeObject
200	*/
201	public function first()
202	{
203	return \count($this->data) > 0 ? $this->data[0] : null;
204	}
205
206	/**
207	* Gets the last item from the current page. Returns `null` if the current page is empty.
208	*
209	* @return null\|TStripeObject
210	*/
211	public function last()
212	{
213	return \count($this->data) > 0 ? $this->data[\count($this->data) - 1] : null;
214	}
215
216	private function extractPathAndUpdateParams($params)
217	{
218	$url = \parse_url($this->url);
219
220	if (!isset($url['path'])) {
221	throw new Exception\UnexpectedValueException("Could not parse list url into parts: {$url}");
222	}
223
224	if (isset($url['query'])) {
225	// If the URL contains a query param, parse it out into $params so they
226	// don't interact weirdly with each other.
227	$query = [];
228	\parse_str($url['query'], $query);
229	$params = \array_merge($params ?: [], $query);
230	}
231
232	return [$url['path'], $params];
233	}
234	}
235