Iterators¶

Common behaviour¶

$iterator = $computeService->flavorList();

There are two ways to traverse an iterator. The first is the longer, more traditional way:

while ($iterator->valid()) {
    $flavor = $iterator->current();

    // do stuff..
    echo $flavor->id;

    $iterator->next();
}

There is also a shorter and more intuitive version:

foreach ($iterator as $flavor) {
    // do stuff...
    echo $flavor->id;
}

Because the iterator implements PHP’s native Iterator interface, it can inherit all the native functionality of traversible data structures with foreach.

Very important note¶

Until now, users have been expected to do this:

while ($flavor = $iterator->next()) {
   // ...
}

which is incorrect. The single responsibility of next is to move the internal pointer forward. It is the job of current to retrieve the current element.

For your convenience, these two Iterator classes are fully backward compatible: they exhibit all the functionality you’d expect from a correctly implemented iterator, but they also allow previous behaviour.

Using paginated collections¶

For large collections, such as retrieving DataObjects from CloudFiles/Swift, you need to use pagination. Each resource will have a different limit per page; so once that page is traversed, there needs to be another API call to retrieve to next page’s resources.

There are two key concepts:

• limit is the amount of resources returned per page
• marker is the way you define a starting point. It is some form of identifier that allows the collection to begin from a specific resource

Setting up a PaginatedIterator¶

use OpenCloud\Common\Collection\PaginatedIterator;

$service = $client->computeService();

$flavors = PaginatedIterator::factory($service, array(
    'resourceClass'  => 'Flavor',
    'baseUrl'        => $service->getUrl('flavors')
    'limit.total'    => 350,
    'limit.page'     => 100,
    'key.collection' => 'flavors'
));

foreach ($flavors as $flavor) {
    echo $flavor->getId();
}

As you can see, there are a lot of configuration parameters to pass in - and getting it right can be quite fiddly, involving a lot of API research. For this reason, using the convenience methods like flavorList is recommended because it hides the complexity.