PHP Class lithium\util\Collection

Collection objects can act very much like arrays. This is especially evident in creating new objects, or by converting Collection into an actual array: {{{ $coll = new Collection(); $coll[] = 'foo'; $coll[0] --> 'foo' $coll = new Collection(array('items' => array('foo'))); $coll[0] --> 'foo' $array = $coll->to('array); }}} Apart from array-like data access, Collections allow for filtering and iteration methods: {{{ $coll = new Collection(array('items' => array(0, 1, 2, 3, 4))); $coll->first(); // 1 (the first non-empty value) $coll->current(); // 0 $coll->next(); // 1 $coll->next(); // 2 $coll->next(); // 3 $coll->prev(); // 2 $coll->rewind(); // 0 }}}

See link: http://us.php.net/manual/en/class.arrayaccess.php

See link: http://us.php.net/manual/en/class.iterator.php

See link: http://us.php.net/manual/en/class.countable.php

Inheritance: extends lithium\core\Object, implements ArrayAccess, implements Iterator, implements Countable

Show file Open project: unionofrad/lithium Class Usage Examples

Protected Properties

Property	Type	Description
$_autoConfig	array	Allows a collection's items to be automatically assigned from class construction options.
$_data	array	The items contained in the collection.
$_formats	array	Accessed via the formats() method.

Public Methods

Method	Description
__call ( string $method, array $parameters = [] ) : mixed	Hook to handle dispatching of methods against all items in the collection.
append ( mixed $value )	Appends an item.
count ( ) : integer	Counts the items of the object.
current ( ) : mixed	Returns the current item.
each ( callback $filter ) : Collection	Applies a callback to all items in the collection.
end ( ) : mixed	Moves forward to the last item.
find ( callback $filter, array $options = [] ) : mixed	Filters a copy of the items in the collection.
first ( callback $filter = null ) : mixed	Returns the first non-empty value in the collection after a filter is applied, or rewinds the collection and returns the first value.
formats ( string $format, mixed $handler = null ) : mixed	Accessor method for adding format handlers to instances and subclasses of Collection.
invoke ( string $method, array $params = [], array $options = [] ) : mixed	Handles dispatching of methods against all items in the collection.
key ( ) : scalar	Returns the key of the current item.
keys ( ) : array	Returns the item keys.
map ( callback $filter, array $options = [] ) : mixed	Applies a callback to a copy of all data in the collection and returns the result.
next ( ) : The	Move forwards to the next item.
offsetExists ( string $offset ) : boolean	Checks whether or not an offset exists.
offsetGet ( string $offset ) : mixed	Returns the value at specified offset.
offsetSet ( string $offset, mixed $value ) : mixed	Assigns a value to the specified offset.
offsetUnset ( string $offset )	Unsets an offset.
prev ( ) : mixed	Moves backward to the previous item. If already at the first item, moves to the last one.
reduce ( callback $reducer, mixed $initial = false ) : mixed	Reduce, or fold, a collection down to a single value
respondsTo ( string $method, boolean $internal = false ) : boolean	Determines if a given method can be called.
rewind ( ) : mixed	Rewinds to the first item.
sort ( string \| callable $sorter = 'sort', array $options = [] ) : Collection	Sorts the objects in the collection.
to ( string $format, array $options = [] ) : mixed	Converts a Collection object to another type of object, or a simple type such as an array.
toArray ( mixed $data, array $options = [] ) : array	Exports a Collection instance to an array. Used by Collection::to().
valid ( ) : boolean	Checks if current position is valid.

Protected Methods

Method	Description
_init ( ) : void	Initializes the collection object by merging in collection items and removing redundant object properties.
_to ( $format, &$data, &$options )

Method Details

__call() public method

Hook to handle dispatching of methods against all items in the collection.

public __call ( string $method, array $parameters = [] ) : mixed
$method	string
$parameters	array
return	mixed

_init() protected method

Initializes the collection object by merging in collection items and removing redundant object properties.

protected _init ( ) : void
return	void

_to() protected method

protected _to ( $format, &$data, &$options )

append() public method

Appends an item.

public append ( mixed $value )
$value	mixed	The item to append.

count() public method

Counts the items of the object.

public count ( ) : integer
return	integer	Returns the number of items in the collection.

current() public method

Returns the current item.

public current ( ) : mixed
return	mixed	The current item or `false` on failure.

each() public method

Applies a callback to all items in the collection.

See link: http://php.net/array_map

public each ( callback $filter ) : Collection
$filter	callback	The filter to apply.
return	Collection	This collection instance.

end() public method

Moves forward to the last item.

public end ( ) : mixed
return	mixed	The current item after moving.

find() public method

Filters a copy of the items in the collection.

public find ( callback $filter, array $options = [] ) : mixed
$filter	callback	Callback to use for filtering.
$options	array	The available options are: - `'collect'`: If `true`, the results will be returned wrapped in a new `Collection` object or subclass. Defaults to `true`.
return	mixed	The filtered items. Will be an array unless `'collect'` is defined in the `$options` argument, then an instance of this class will be returned.

first() public method

Returns the first non-empty value in the collection after a filter is applied, or rewinds the collection and returns the first value.

See also: lithium\util\Collection::rewind()

public first ( callback $filter = null ) : mixed
$filter	callback	A closure through which collection values will be passed. If the return value of this function is non-empty, it will be returned as the result of the method call. If `null`, the collection is rewound (see `rewind()`) and the first item is returned.
return	mixed	Returns the first non-empty collection value returned from `$filter`.

formats() public static method

The values assigned are used by Collection::to() to convert Collection instances into different formats, i.e. JSON. This can be accomplished in two ways. First, format handlers may be registered on a case-by-case basis, as in the following: Collection::formats('json', function($collection, $options) { return json_encode($collection->to('array')); }); You can also implement the above as a static class method, and register it as follows: Collection::formats('json', '\my\custom\Formatter::toJson'); Alternatively, you can implement a class that can handle several formats. This class must implement two static methods: - A formats() method, which returns an array indicating what formats it handles. - A to() method, which handles the actual conversion. Once a class implements these methods, it may be registered per the following: Collection::formats('\lithium\net\http\Media'); For reference on how to implement these methods, see the Media class. Once a handler is registered, any instance of Collection or a subclass can be converted to the format(s) supported by the class or handler, using the to() method.

invoke() public method

Handles dispatching of methods against all items in the collection.

public invoke ( string $method, array $params = [], array $options = [] ) : mixed
$method	string	The name of the method to call on each instance in the collection.
$params	array	The parameters to pass on each method call.
$options	array	Specifies options for how to run the given method against the object collection. The available options are: - `'collect'`: If `true`, the results of this method call will be returned wrapped in a new `Collection` object or subclass. - `'merge'`: Used primarily if the method being invoked returns an array. If set to `true`, merges all results arrays into one.
return	mixed	Returns either an array of the return values of the methods, or the return values wrapped in a `Collection` instance.

key() public method

Returns the key of the current item.

public key ( ) : scalar
return	scalar	Scalar on success or `null` on failure.

keys() public method

Returns the item keys.

public keys ( ) : array
return	array	The keys of the items.

map() public method

Applies a callback to a copy of all data in the collection and returns the result.

See link: http://php.net/array_map

public map ( callback $filter, array $options = [] ) : mixed
$filter	callback	The filter to apply.
$options	array	The available options are: - `'collect'`: If `true`, the results will be returned wrapped in a new `Collection` object or subclass.
return	mixed	The filtered items. Will be an array unless `'collect'` is defined in the `$options` argument, then an instance of this class will be returned.

next() public method

Move forwards to the next item.

public next ( ) : The
return	The	current item after moving or `false` on failure.

offsetExists() public method

Checks whether or not an offset exists.

public offsetExists ( string $offset ) : boolean
$offset	string	An offset to check for.
return	boolean	`true` if offset exists, `false` otherwise.

offsetGet() public method

Returns the value at specified offset.

public offsetGet ( string $offset ) : mixed
$offset	string	The offset to retrieve.
return	mixed	Value at offset.

offsetSet() public method

Assigns a value to the specified offset.

public offsetSet ( string $offset, mixed $value ) : mixed
$offset	string	The offset to assign the value to.
$value	mixed	The value to set.
return	mixed	The value which was set.

offsetUnset() public method

Unsets an offset.

public offsetUnset ( string $offset )
$offset	string	The offset to unset.

prev() public method

Moves backward to the previous item. If already at the first item, moves to the last one.

public prev ( ) : mixed
return	mixed	The current item after moving or the last item on failure.

reduce() public method

Reduce, or fold, a collection down to a single value

See link: http://php.net/array_reduce

public reduce ( callback $reducer, mixed $initial = false ) : mixed
$reducer	callback	The reduce function, i.e. `function($carry, $item) { return ... }`
$initial	mixed	Initial value passed to the reduce function as `$carry`, defaults to `false`.
return	mixed	A single reduced value.

respondsTo() public method

Determines if a given method can be called.

public respondsTo ( string $method, boolean $internal = false ) : boolean
$method	string	Name of the method.
$internal	boolean	Provide `true` to perform check from inside the class/object. When `false` checks also for public visibility; defaults to `false`.
return	boolean	Returns `true` if the method can be called, `false` otherwise.

rewind() public method

Rewinds to the first item.

public rewind ( ) : mixed
return	mixed	The current item after rewinding.

sort() public method

Sorts the objects in the collection.

See link: http://php.net/sort

See link: http://php.net/usort

See link: http://php.net/strcmp

public sort ( string \| callable $sorter = 'sort', array $options = [] ) : Collection
$sorter	string \| callable	The sorter for the data. Either a callable to use as the sort function or a string with the name of a well-known sort function like `'natsort'` or a compare function like `'strcmp'`. Defaults to `'sort'`.
$options	array	Reserved for future use.
return	Collection	Returns itself.

to() public method

The supported values of $format depend on the format handlers registered in the static property Collection::$_formats. The Collection class comes with built-in support for array conversion, but other formats may be registered. Once the appropriate handlers are registered, a Collection instance can be converted into any handler-supported format, i.e.: $collection->to('json'); // returns a JSON string $collection->to('xml'); // returns an XML string _Please note that Lithium does not ship with a default XML handler, but one can be configured easily._

See also: lithium\util\Collection::formats()

See also: lithium\util\Collection::$_formats

public to ( string $format, array $options = [] ) : mixed
$format	string	By default the only supported value is `'array'`. However, additional format handlers can be registered using the `formats()` method.
$options	array	Options for converting this collection: - `'internal'` _boolean_: Indicates whether the current internal representation of the collection should be exported. Defaults to `false`, which uses the standard iterator interfaces. This is useful for exporting record sets, where records are lazy-loaded, and the collection must be iterated in order to fetch all objects.
return	mixed	The object converted to the value specified in `$format`; usually an array or string.

toArray() public static method

Exports a Collection instance to an array. Used by Collection::to().

public static toArray ( mixed $data, array $options = [] ) : array
$data	mixed	Either a `Collection` instance, or an array representing a `Collection`'s internal state.
$options	array	Options used when converting `$data` to an array: - `'handlers'` _array_: An array where the keys are fully-namespaced class names, and the values are closures that take an instance of the class as a parameter, and return an array or scalar value that the instance represents.
return	array	Returns the value of `$data` as a pure PHP array, recursively converting all sub-objects and other values to their closest array or scalar equivalents.

valid() public method

Checks if current position is valid.

public valid ( ) : boolean
return	boolean	`true` if valid, `false` otherwise.

Property Details

$_autoConfig protected property

Allows a collection's items to be automatically assigned from class construction options.

protected array $_autoConfig
return	array

$_data protected property

The items contained in the collection.

protected array $_data
return	array

$_formats protected static property

Accessed via the formats() method.

See also: lithium\util\Collection::formats()

protected static array $_formats
return	array

public static formats ( string $format, mixed $handler = null ) : mixed
$format	string	A string representing the name of the format that a `Collection` can be converted to. This corresponds to the `$format` parameter in the `to()` method. Alternatively, the fully-namespaced class name of a format-handler class.
$handler	mixed	If `$format` is the name of a format string, `$handler` should be the function that handles the conversion, either an anonymous function, or a reference to a method name in `"Class::method"` form. If `$format` is a class name, can be `null`.
return	mixed	Returns the value of the format handler assigned.