==================
|
Resource iterators
|
==================
|
|
Web services often implement pagination in their responses which requires the end-user to issue a series of consecutive
|
requests in order to fetch all of the data they asked for. Users of your web service client should not be responsible
|
for implementing the logic involved in iterating through pages of results. Guzzle provides a simple resource iterator
|
foundation to make it easier on web service client developers to offer a useful abstraction layer.
|
|
Getting an iterator from a client
|
---------------------------------
|
|
ResourceIteratorInterface Guzzle\Service\Client::getIterator($command [, array $commandOptions, array $iteratorOptions ])
|
|
The ``getIterator`` method of a ``Guzzle\Service\ClientInterface`` object provides a convenient interface for
|
instantiating a resource iterator for a specific command. This method implicitly uses a
|
``Guzzle\Service\Resource\ResourceIteratorFactoryInterface`` object to create resource iterators. Pass an
|
instantiated command object or the name of a command in the first argument. When passing the name of a command, the
|
command factory of the client will create the command by name using the ``$commandOptions`` array. The third argument
|
may be used to pass an array of options to the constructor of the instantiated ``ResourceIteratorInterface`` object.
|
|
.. code-block:: php
|
|
$iterator = $client->getIterator('get_users');
|
|
foreach ($iterator as $user) {
|
echo $user['name'] . ' age ' . $user['age'] . PHP_EOL;
|
}
|
|
The above code sample might execute a single request or a thousand requests. As a consumer of a web service, I don't
|
care. I just want to iterate over all of the users.
|
|
Iterator options
|
~~~~~~~~~~~~~~~~
|
|
The two universal options that iterators should support are ``limit`` and ``page_size``. Using the ``limit`` option
|
tells the resource iterator to attempt to limit the total number of iterated resources to a specific amount. Keep in
|
mind that this is not always possible due to limitations that may be inherent to a web service. The ``page_size``
|
option is used to tell a resource iterator how many resources to request per page of results. Much like the ``limit``
|
option, you can not rely on getting back exactly the number of resources your specify in the ``page_size`` option.
|
|
.. note::
|
|
The ``limit`` and ``page_size`` options can also be specified on an iterator using the ``setLimit($limit)`` and
|
``setPageSize($pageSize)`` methods.
|
|
Resolving iterator class names
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
The default resource iterator factory of a client object expects that your iterators are stored under the ``Model``
|
folder of your client and that an iterator is names after the CamelCase name of a command followed by the word
|
"Iterator". For example, if you wanted to create an iterator for the ``get_users`` command, then your iterator class
|
would be ``Model\GetUsersIterator`` and would be stored in ``Model/GetUsersIterator.php``.
|
|
Creating an iterator
|
--------------------
|
|
While not required, resource iterators in Guzzle typically iterate using a ``Guzzle\Service\Command\CommandInterface``
|
object. ``Guzzle\Service\Resource\ResourceIterator``, the default iterator implementation that you should extend,
|
accepts a command object and array of iterator options in its constructor. The command object passed to the resource
|
iterator is expected to be ready to execute and not previously executed. The resource iterator keeps a reference of
|
this command and clones the original command each time a subsequent request needs to be made to fetch more data.
|
|
Implement the sendRequest method
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
The most important thing (and usually the only thing) you need to do when creating a resource iterator is to implement
|
the ``sendRequest()`` method of the resource iterator. The ``sendRequest()`` method is called when you begin
|
iterating or if there are no resources left to iterate and it you expect to retrieve more resources by making a
|
subsequent request. The ``$this->command`` property of the resource iterator is updated with a cloned copy of the
|
original command object passed into the constructor of the iterator. Use this command object to issue your subsequent
|
requests.
|
|
The ``sendRequest()`` method must return an array of the resources you retrieved from making the subsequent call.
|
Returning an empty array will stop the iteration. If you suspect that your web service client will occasionally return
|
an empty result set but still requires further iteration, then you must implement a sort of loop in your
|
``sendRequest()`` method that will continue to issue subsequent requests until your reach the end of the paginated
|
result set or until additional resources are retrieved from the web service.
|
|
Update the nextToken property
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
Beyond fetching more results, the ``sendRequest()`` method is responsible for updating the ``$this->nextToken``
|
property of the iterator. Setting this property to anything other than null tells the iterator that issuing a
|
subsequent request using the nextToken value will probably return more results. You must continually update this
|
value in your ``sendRequest()`` method as each response is received from the web service.
|
|
Example iterator
|
----------------
|
|
Let's say you want to implement a resource iterator for the ``get_users`` command of your web service. The
|
``get_users`` command receives a response that contains a list of users, and if there are more pages of results to
|
retrieve, returns a value called ``next_user``. This return value is known as the **next token** and should be used to
|
issue subsequent requests.
|
|
Assume the response to a ``get_users`` command returns JSON data that looks like this:
|
|
.. code-block:: javascript
|
|
{
|
"users": [
|
{ "name": "Craig Johnson", "age": 10 },
|
{ "name": "Tom Barker", "age": 20 },
|
{ "name": "Bob Mitchell", "age": 74 }
|
],
|
"next_user": "Michael Dowling"
|
}
|
|
Assume that because there is a ``next_user`` value, there will be more users if a subsequent request is issued. If the
|
``next_user`` value is missing or null, then we know there are no more results to fetch. Let's implement a resource
|
iterator for this command.
|
|
.. code-block:: php
|
|
namespace MyService\Model;
|
|
use Guzzle\Service\Resource\ResourceIterator;
|
|
/**
|
* Iterate over a get_users command
|
*/
|
class GetUsersIterator extends ResourceIterator
|
{
|
protected function sendRequest()
|
{
|
// If a next token is set, then add it to the command
|
if ($this->nextToken) {
|
$this->command->set('next_user', $this->nextToken);
|
}
|
|
// Execute the command and parse the result
|
$result = $this->command->execute();
|
|
// Parse the next token
|
$this->nextToken = isset($result['next_user']) ? $result['next_user'] : false;
|
|
return $result['users'];
|
}
|
}
|
|
As you can see, it's pretty simple to implement an iterator. There are a few things that you should notice from this
|
example:
|
|
1. You do not need to create a new command in the ``sendRequest()`` method. A new command object is cloned from the
|
original command passed into the constructor of the iterator before the ``sendRequest()`` method is called.
|
Remember that the resource iterator expects a command that has not been executed.
|
2. When the ``sendRequest()`` method is first called, you will not have a ``$this->nextToken`` value, so always check
|
before setting it on a command. Notice that the next token is being updated each time a request is sent.
|
3. After fetching more resources from the service, always return an array of resources.
|
