media-cloud-sync / includes / sdk / google / google / gax / src / PagedListResponse.php

PagedListResponse.php in Media Cloud Sync 1.0.1, at includes/sdk/google/google/gax/src/PagedListResponse.php

190 lines 6.8 KB

Raw Download Zip

1	<?php
2
3	/*
4	* Copyright 2016 Google LLC
5	* All rights reserved.
6	*
7	* Redistribution and use in source and binary forms, with or without
8	* modification, are permitted provided that the following conditions are
9	* met:
10	*
11	* * Redistributions of source code must retain the above copyright
12	* notice, this list of conditions and the following disclaimer.
13	* * Redistributions in binary form must reproduce the above
14	* copyright notice, this list of conditions and the following disclaimer
15	* in the documentation and/or other materials provided with the
16	* distribution.
17	* * Neither the name of Google Inc. nor the names of its
18	* contributors may be used to endorse or promote products derived from
19	* this software without specific prior written permission.
20	*
21	* THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
22	* "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
23	* LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
24	* A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
25	* OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
26	* SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
27	* LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
28	* DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
29	* THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
30	* (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
31	* OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
32	*/
33	namespace Dudlewebs\WPMCS\Google\ApiCore;
34
35	use Generator;
36	use IteratorAggregate;
37	/**
38	* Response object for paged results from a list API method
39	*
40	* The PagedListResponse object is returned by API methods that implement
41	* pagination, and makes it easier to access multiple pages of results
42	* without having to manually manipulate page tokens. Pages are retrieved
43	* lazily, with additional API calls being made as additional results
44	* are required.
45	*
46	* The list elements can be accessed in the following ways:
47	* - As a single iterable used in a foreach loop or via the getIterator method
48	* - As pages of elements, using the getPage and iteratePages methods
49	* - As fixed size collections of elements, using the
50	* getFixedSizeCollection and iterateFixedSizeCollections methods
51	*
52	* Example of using PagedListResponse as an iterator:
53	* ```
54	* $pagedListResponse = $client->getList(...);
55	* foreach ($pagedListResponse as $element) {
56	* // doSomethingWith($element);
57	* }
58	* ```
59	*
60	* Example of iterating over each page of elements:
61	* ```
62	* $pagedListResponse = $client->getList(...);
63	* foreach ($pagedListResponse->iteratePages() as $page) {
64	* foreach ($page as $element) {
65	* // doSomethingWith($element);
66	* }
67	* }
68	* ```
69	*
70	* Example of accessing the current page, and manually iterating
71	* over pages:
72	* ```
73	* $pagedListResponse = $client->getList(...);
74	* $page = $pagedListResponse->getPage();
75	* // doSomethingWith($page);
76	* while ($page->hasNextPage()) {
77	* $page = $page->getNextPage();
78	* // doSomethingWith($page);
79	* }
80	* ```
81	*/
82	class PagedListResponse implements IteratorAggregate
83	{
84	private $firstPage;
85	/**
86	* PagedListResponse constructor.
87	*
88	* @param Page $firstPage A page containing response details.
89	*/
90	public function __construct(Page $firstPage)
91	{
92	$this->firstPage = $firstPage;
93	}
94	/**
95	* Returns an iterator over the full list of elements. If the
96	* API response contains a (non-empty) next page token, then
97	* the PagedListResponse object will make calls to the underlying
98	* API to retrieve additional elements as required.
99	*
100	* NOTE: The result of this method is the same as getIterator().
101	* Prefer using getIterator(), or iterate directly on the
102	* PagedListResponse object.
103	*
104	* @return Generator
105	* @throws ValidationException
106	*/
107	public function iterateAllElements()
108	{
109	return $this->getIterator();
110	}
111	/**
112	* Returns an iterator over the full list of elements. If the
113	* API response contains a (non-empty) next page token, then
114	* the PagedListResponse object will make calls to the underlying
115	* API to retrieve additional elements as required.
116	*
117	* @return Generator
118	* @throws ValidationException
119	*/
120	#[\ReturnTypeWillChange]
121	public function getIterator()
122	{
123	foreach ($this->iteratePages() as $page) {
124	foreach ($page as $key => $element) {
125	yield $key => $element;
126	}
127	}
128	}
129	/**
130	* Return the current page of results.
131	*
132	* @return Page
133	*/
134	public function getPage()
135	{
136	return $this->firstPage;
137	}
138	/**
139	* Returns an iterator over pages of results. The pages are
140	* retrieved lazily from the underlying API.
141	*
142	* @return Page[]
143	* @throws ValidationException
144	*/
145	public function iteratePages()
146	{
147	return $this->getPage()->iteratePages();
148	}
149	/**
150	* Returns a collection of elements with a fixed size set by
151	* the collectionSize parameter. The collection will only contain
152	* fewer than collectionSize elements if there are no more
153	* pages to be retrieved from the server.
154	*
155	* NOTE: it is an error to call this method if an optional parameter
156	* to set the page size is not supported or has not been set in the
157	* original API call. It is also an error if the collectionSize parameter
158	* is less than the page size that has been set.
159	*
160	* @param int $collectionSize
161	* @throws ValidationException if a FixedSizeCollection of the specified size cannot be constructed
162	* @return FixedSizeCollection
163	*/
164	public function expandToFixedSizeCollection(int $collectionSize)
165	{
166	return $this->getPage()->expandToFixedSizeCollection($collectionSize);
167	}
168	/**
169	* Returns an iterator over fixed size collections of results.
170	* The collections are retrieved lazily from the underlying API.
171	*
172	* Each collection will have collectionSize elements, with the
173	* exception of the final collection which may contain fewer
174	* elements.
175	*
176	* NOTE: it is an error to call this method if an optional parameter
177	* to set the page size is not supported or has not been set in the
178	* original API call. It is also an error if the collectionSize parameter
179	* is less than the page size that has been set.
180	*
181	* @param int $collectionSize
182	* @throws ValidationException if a FixedSizeCollection of the specified size cannot be constructed
183	* @return Generator\|FixedSizeCollection[]
184	*/
185	public function iterateFixedSizeCollections(int $collectionSize)
186	{
187	return $this->expandToFixedSizeCollection($collectionSize)->iterateCollections();
188	}
189	}
190