Provides an abstraction for working with ordered sets of objects
Collection objects are used whenever there are multiples; for example,
multiple objects in a container, or multiple servers in a service.
Methods summary
public
|
#
__construct( OpenCloud\Common\Service $service, string $itemclass, array $array )
A Collection is an array of objects
A Collection is an array of objects
Some assumptions:
- The
Collection class assumes that there exists on its service a
factory method with the same name of the class. For example, if you create a
Collection of class Foobar , it will attempt to call the method
parent::Foobar() to create instances of that class.
- It assumes that the factory method can take an array of values, and it
passes that to the method.
Parameters
- $service
OpenCloud\Common\Service
$service - the service associated with the collection
- $itemclass
string $itemclass - the Class of each item in the collection (assumed to be the name of
the factory method)
- $array
array $arr - the input array
|
public
|
#
setItemList( array $array )
Set the entire data array.
Set the entire data array.
Parameters
|
public
array
|
#
getItemList( )
Retrieve the entire data array.
Retrieve the entire data array.
Returns
array
|
public
integer
|
#
count( )
Returns the number of items in the collection
Returns the number of items in the collection
For most services, this is the total number of items. If the Collection is
paginated, however, this only returns the count of items in the current page of
data.
Returns
integer
|
public
|
#
size( )
Pseudonym for count()
CodeCoverageIgnore
|
public
OpenCloud\Common\Service
|
#
service( )
Retrieves the service associated with the Collection
Retrieves the service associated with the Collection
Returns
|
public
|
#
reset( )
Resets the pointer to the beginning, but does NOT return the first item
Resets the pointer to the beginning, but does NOT return the first item
Api
|
public
OpenCloud\Common\Base
|
#
first( )
Resets the collection pointer back to the first item in the page and returns
it
Resets the collection pointer back to the first item in the page and returns
it
This is useful if you're only interested in the first item in the page.
Returns
Api
|
public
OpenCloud\Common\Base
|
#
next( )
Returns the next item in the page
Returns the next item in the page
Returns
Api
|
public
|
#
sort( string $keyname = 'id' )
sorts the collection on a specified key
sorts the collection on a specified key
Note: only top-level keys can be used as the sort key. Note that this only
sorts the data in the current page of the Collection (for multi-page data).
Parameters
- $keyname
string $keyname the name of the field to use as the sort key
Api
|
public
|
#
select( callable $testfunc )
selects only specified items from the Collection
selects only specified items from the Collection
This provides a simple form of filtering on Collections. For each item in the
collection, it calls the callback function, passing it the item. If the callback
returns TRUE , then the item is retained; if it returns
FALSE , then the item is deleted from the collection.
Note that this should not supersede server-side filtering; the
Collection::Select() method requires that all of the data
for the Collection be retrieved from the server before the filtering is
performed; this can be very inefficient, especially for large data sets. This
method is mostly useful on smaller-sized sets.
Example:
$services = $connection->ServiceList();
$services->Select(function($item){ return $item->region=='ORD';});
Select() is destructive; that is, it actually removes
entries from the collection. For example, if you use Select() to
find items with the ID > 10, then use it again to find items that are <=
10, it will return an empty list.
Parameters
- $testfunc
callable $testfunc a callback function that is passed each item in turn. Note that
Select() performs an explicit test for FALSE , so
functions like strpos() need to be cast into a boolean value (and
not just return the integer).
Throws
DomainError if callback doesn't return a boolean value
Api
Returns
void
|
public
OpenCloud\Common\Collection
|
#
nextPage( )
returns the Collection object for the next page of results, or FALSE if there
are no more pages
returns the Collection object for the next page of results, or FALSE if there
are no more pages
Generally, the structure for a multi-page collection will look like this:
$coll = $obj->Collection(); do { while($item = $coll->Next()) { // do
something with the item } } while ($coll = $coll->NextPage());
Returns
Api
|
public
|
#
setNextPageCallback( callable $callback, string $url )
for paginated collection, sets the callback function and URL for the next
page
for paginated collection, sets the callback function and URL for the next
page
The callback function should have the signature:
function Whatever($class, $url, $parent)
and the $url should be the URL of the next page of results
Parameters
- $callback
callable $callback the name of the function (or array of object, function name)
- $url
string $url the URL of the next page of results
|