Documentation

PaginatedIterator extends ResourceIterator
in package

OpenCloud

Common

Collection

implements Iterator

Class ResourceIterator is tasked with iterating over resource collections - many of which are paginated. Based on a base URL, the iterator will append elements based on further requests to the API. Each time this happens, query parameters (marker) are updated based on the current value.

Interfaces, Classes and Traits

Iterator

LIMIT = 'limit'
MARKER = 'marker'
$currentMarker : string
$defaults : array<string|int, mixed>
$elements : mixed
$nextUrl : Url
$options : array<string|int, mixed>
$position : int
$required : array<string|int, mixed>
$resourceParent : object
__construct() : mixed
append() : mixed: Appends a value to the container.
appendElements() : $this: Append an array of standard objects to the current collection.
appendNewCollection() : $this|bool: Retrieve a new page of elements from the API (based on a new request), parse its response, and append them to the collection.
constructNextUrl() : Url|string: Make the next page URL.
constructResource() : mixed: Using a standard object, this method populates a resource model with all the object data. It does this using a whatever method the parent object has for resource creation.
count() : int
current() : mixed
currentElement() : mixed
extractNextLink() : bool: Based on the response body, extract the explicitly set "link" value if provided.
factory() : static: Basic factory method to easily instantiate a new ResourceIterator.
first() : mixed
getElement() : mixed
getOption() : null
getOptions() : array<string|int, mixed>
key() : int|mixed: Return the current position/internal pointer.
next() : mixed: {@inheritDoc} Also update the current marker.
offsetExists() : bool: Checks to see whether a particular offset key exists.
offsetGet() : mixed|null: Get the value for a particular offset key.
offsetSet() : mixed: Sets a value to a particular offset.
offsetUnset() : mixed: Unset a particular key.
parseResponseBody() : array<string|int, mixed>: Based on the response from the API, parse it for the data we need (i.e. an meaningful array of elements).
populateAll() : mixed: Walk the entire collection, populating everything.
rewind() : mixed: {@inheritDoc} Also reset current marker.
search() : mixed
setBaseUrl() : $this
setElements() : $this
setOption() : $this: Set a particular option.
setOptions() : $this
setResourceParent() : $this
sort() : mixed
updateMarkerToCurrent() : mixed: Update the current marker based on the current element. The marker will be based on a particular property of this current element, so you must retrieve it first.
valid() : bool: This method is called after self::rewind() and self::next() to check if the current position is valid.
valueExists() : bool: Checks to see whether a particular value exists.
parseOptions() : mixed
setMarkerFromElement() : mixed
shouldAppend() : mixed

LIMIT


    public
    mixed
    LIMIT
    = 'limit'

MARKER


    public
    mixed
    MARKER
    = 'marker'

$currentMarker


    protected
        string
    $currentMarker

Used for requests which append elements.

$defaults


    protected
        array<string|int, mixed>
    $defaults
     = array(
    // Collection limits
    'limit.total' => 10000,
    'limit.page' => 100,
    // The "links" element key in response
    'key.links' => 'links',
    // JSON structure
    'key.collection' => null,
    'key.collectionElement' => null,
    // The property used as the marker
    'key.marker' => 'name',
    // Options for "next page" request
    'request.method' => 'GET',
    'request.headers' => array(),
    'request.body' => null,
    'request.curlOptions' => array(),
)

Fallback defaults if options are not explicitly set or provided.

$elements


    protected
        mixed
    $elements

$nextUrl


    protected
        Url
    $nextUrl

The next URL for pagination

$options


    protected
        array<string|int, mixed>
    $options

The options for this iterator.

$position


    protected
        int
    $position

Internal pointer of the iterator - reveals its current position.

$required


    protected
        array<string|int, mixed>
    $required
     = array('resourceClass', 'baseUrl')

Required options

$resourceParent


    protected
        object
    $resourceParent

The parent object which resource models are instantiated from. The parent needs to have appropriate methods to instantiate the particular object.

__construct()


    public
                __construct([mixed $data = array() ]) : mixed

Parameters

$data : mixed = array()

Return values

mixed —

append()

Appends a value to the container.


    public
                append( $value) : mixed

Parameters

$value :

Return values

mixed —

appendElements()

Append an array of standard objects to the current collection.


    public
                appendElements(array<string|int, mixed> $elements) : $this

Parameters

$elements : array<string|int, mixed>

Return values

$this —

appendNewCollection()

Retrieve a new page of elements from the API (based on a new request), parse its response, and append them to the collection.


    public
                appendNewCollection() : $this|bool

Return values

$this|bool —

constructNextUrl()

Make the next page URL.


    public
                constructNextUrl() : Url|string

Return values

Url|string —

constructResource()

Using a standard object, this method populates a resource model with all the object data. It does this using a whatever method the parent object has for resource creation.


    public
                constructResource( $object) : mixed

Parameters

$object :: Standard object

Return values

mixed —

count()


    public
                count() : int

Return values

int —

current()


    public
                current() : mixed

Return values

mixed —

currentElement()


    public
                currentElement() : mixed

Return values

mixed —

extractNextLink()

Based on the response body, extract the explicitly set "link" value if provided.


    public
                extractNextLink( $body) : bool

Parameters

$body :

Return values

bool —

factory()

Basic factory method to easily instantiate a new ResourceIterator.


    public
            static    factory(mixed $parent[, array<string|int, mixed> $options = array() ][, array<string|int, mixed> $data = null ]) : static

Parameters

$parent : mixed: The parent object
$options : array<string|int, mixed> = array(): Iterator options
$data : array<string|int, mixed> = null: Optional data to set initially

Return values

static —

first()


    public
                first() : mixed

Return values

mixed —

getElement()


    public
                getElement(mixed $offset) : mixed

Parameters

$offset : mixed

Return values

mixed —

getOption()


    public
                getOption( $key) : null

Parameters

$key :

Return values

null —

getOptions()


    public
                getOptions() : array<string|int, mixed>

Return values

array<string|int, mixed> —

Options for the resource iterator.

key()

Return the current position/internal pointer.


    public
                key() : int|mixed

Return values

int|mixed —

next()

{@inheritDoc} Also update the current marker.


    public
                next() : mixed

Return values

mixed —

offsetExists()

Checks to see whether a particular offset key exists.


    public
                offsetExists(mixed $offset) : bool

Parameters

$offset : mixed

Return values

bool —

offsetGet()

Get the value for a particular offset key.


    public
                offsetGet(mixed $offset) : mixed|null

Parameters

$offset : mixed

Return values

mixed|null —

offsetSet()

Sets a value to a particular offset.


    public
                offsetSet(mixed $offset, mixed $value) : mixed

Parameters

$offset : mixed
$value : mixed

Return values

mixed —

offsetUnset()

Unset a particular key.


    public
                offsetUnset(mixed $offset) : mixed

Parameters

$offset : mixed

Return values

mixed —

parseResponseBody()

Based on the response from the API, parse it for the data we need (i.e. an meaningful array of elements).


    public
                parseResponseBody( $body) : array<string|int, mixed>

Parameters

$body :

Return values

array<string|int, mixed> —

populateAll()

Walk the entire collection, populating everything.


    public
                populateAll() : mixed

Return values

mixed —

rewind()

{@inheritDoc} Also reset current marker.


    public
                rewind() : mixed

Return values

mixed —

search()


    public
                search(mixed $callback) : mixed

Parameters

$callback : mixed

Return values

mixed —

setBaseUrl()


    public
                setBaseUrl(Url $url) : $this

Parameters

$url : Url

Return values

$this —

setElements()


    public
                setElements([array<string|int, mixed> $data = array() ]) : $this

Parameters

$data : array<string|int, mixed> = array()

Return values

$this —

setOption()

Set a particular option.


    public
                setOption( $key,  $value) : $this

Parameters

$key :
$value :

Return values

$this —

setOptions()


    public
                setOptions(array<string|int, mixed> $options) : $this

Parameters

$options : array<string|int, mixed>

Return values

$this —

setResourceParent()


    public
                setResourceParent( $parent) : $this

Parameters

$parent :

Return values

$this —

sort()


    public
                sort() : mixed

Return values

mixed —

updateMarkerToCurrent()

Update the current marker based on the current element. The marker will be based on a particular property of this current element, so you must retrieve it first.


    public
                updateMarkerToCurrent() : mixed

Return values

mixed —

valid()

This method is called after self::rewind() and self::next() to check if the current position is valid.


    public
                valid() : bool

Return values

bool —

valueExists()

Checks to see whether a particular value exists.


    public
                valueExists( $value) : bool

Parameters

$value :

Return values

bool —

parseOptions()


    protected
                parseOptions(array<string|int, mixed> $options) : mixed

Parameters

$options : array<string|int, mixed>

Return values

mixed —

setMarkerFromElement()


    protected
                setMarkerFromElement(mixed $element) : mixed

Parameters

$element : mixed

Return values

mixed —

shouldAppend()


    protected
                shouldAppend() : mixed

Return values

mixed —