Collections are a special type of iterators, with additional helper functions for reading from indexed or sequential set of data (like databases, arrays, object collections etc.). More...

Inheritance diagram for Collection:

Public Member Functions
	__construct (array $options=array())
	__destruct ()
	isEmpty ()
	fetch ($moveNext=true)
	Returns item at current position, advancing to the next row.
	valid ()
	Returns item at current position, staying at the current position.
	currentPosition ()
	Returns current position in the set.
	key ()
	Returns current position in the set.
	next ()
	Moves to the next position.
	rewind ()
	Rewinds to the beginning.
	fetchField ($field, $moveNext=true, $default=null)
	Returns field of an item at current position.
	extractField ($data, $field, $default=null)
	Extracts specified field from data object/value.
	hasField ($field)
	fetchRange ($limit=false, $start=false, $movePosition=true)
	toArray ()
	fetchFieldRange ($field, $limit=false, $start=false, $movePosition=true)
	fetchPosition ($pos, $movePosition=true)
	Fetches item at specified position, with option to stay at current position.
	prefetch ($limit=false, $start=false)
	Items will be prefetched (if needed) in a batch for later retrieval.
	close ()
	Closes the collection and frees up resources.
	isBidirectional ()
	Returns true if data can be traversed in both directions.
	offsetExists ($offset)
	offsetGet ($offset)
	offsetSet ($offset, $value)
	offsetUnset ($offset)
	getCollection ($className=false)
	Returns this collection object.
	getOption ($name, $default=null)
	Returns collection option.
	setOption ($nameOrOptions, $value=null)
	Sets collection option.
Data Fields
	$options
const	OPT_FIELD_EXTRACTOR = 'fieldExtractor'
	Field extraction callback cb($collection, $data, $field, $default) returning extracted values or $default.
const	OPT_BIDIRECTIONAL = 'bidi'
	Makes some collections bidirectional through caching of results.
const	OPT_PREFETCH_AUTO = 'prefetch_auto'
	Automatically prefetches this amount of items, as soon as the last prefetch is used up.
const	OPT_RELEASE_AUTO = 'release_auto'
	Automatically releases results after this many items read.
const	FIELD_INNER = '.'
const	FIELD_ARRAY = 'array()'
	Extracts all fields as array.

Detailed Description

Collections are a special type of iterators, with additional helper functions for reading from indexed or sequential set of data (like databases, arrays, object collections etc.).

Every iterator implements SeekableIterator, however it's not guaranteed, that the iterator can go backwards, at least with a good performance. If it's not supported, iterator will throw an Exception, or trigger a E_USER_NOTICE it it's not optimized for that.

The same applies to count()

Additionaly, as iterators know the structure of handled data sets, it's possible to extract fields from the objects in the data set.

All collections should be closed with close() after using!

Constructor & Destructor Documentation

Collection::__construct ( array $ options = array() )

Collection::__destruct ( )

Member Function Documentation

Collection::close ( )

Closes the collection and frees up resources.

Reimplemented in Collection_Query, Collection_Iterator, Collection_Array, and Collection_Outer.

Collection::currentPosition ( ) [abstract]

Returns current position in the set.

Reimplemented in Collection_Filtered, Collection_Query, Collection_Array, Collection_Outer, and Collection_Iterator.

Collection::extractField	(	$	data,
		$	field,
		$	default = `null`
	)

Extracts specified field from data object/value.

Returns:: mixed

Reimplemented in KWebCollection_Objects, and Collection_Outer.

Collection::fetch ( $ moveNext = true )

Returns item at current position, advancing to the next row.

Parameters:

boolean $moveNext - false to stay at current position

Collection::fetchField	(	$	field,
		$	moveNext = `true`,
		$	default = `null`
	)

Returns field of an item at current position.

On some Collection_Outer collections, You can prepend INNER_FIELD (like: fetchField('.field')) to the field name, to access fields of the inner collection. To access inner collection's value (same as using fetch()), use INNER_FIELD only (like: fetchField('.')). You can go several levels deep this way, but general rule of a thumb is, that if the collection doesn't handle the data (eg. Collection_Filtered), it can be considered as at the same level, as the one that handles underneath it.

Returns:: mixed

Reimplemented in Collection_Outer.

Collection::fetchFieldRange	(	$	field,
		$	limit = `false`,
		$	start = `false`,
		$	movePosition = `true`
	)

Parameters:

Number	of items to prefetch or false
Start	of the prefetch or false for current position

Returns:: mixed

Collection::fetchPosition	(	$	pos,
		$	movePosition = `true`
	)

Fetches item at specified position, with option to stay at current position.

Parameters:

boolean $movePosition - false to stay at current position after fetch

Returns:: mixed

Collection::fetchRange	(	$	limit = `false`,
		$	start = `false`,
		$	movePosition = `true`
	)

Parameters:

Number	of items to prefetch or false
Start	of the prefetch or false for current position

Returns:: array

Collection::getCollection ( $ className = false )

Returns this collection object.

If you provide a $className it will return null if this collection is of a different type

Returns:: Collection

Reimplemented in Collection_Outer.

Collection::getOption	(	$	name,
		$	default = `null`
	)

Returns collection option.

Collection::hasField ( $ field )

Returns:: boolean true if collection contains this field

Reimplemented in Collection_Query, and Collection_Array.

Collection::isBidirectional ( )

Returns true if data can be traversed in both directions.

Returns:: boolean

Reimplemented in Collection_Filtered, Collection_Query, Collection_Iterator, and Collection_Outer.

Collection::isEmpty ( )

Collection::key ( )

Returns current position in the set.

Reimplemented in Collection_Iterator.

Collection::next ( )

Moves to the next position.

Reimplemented in Collection_Filtered, Collection_Query, Collection_Array, Collection_Outer, and Collection_Iterator.

Collection::offsetExists ( $ offset )

Returns:: boolean

Reimplemented in Collection_Iterator.

Collection::offsetGet ( $ offset )

Returns:: mixed

Reimplemented in Collection_Iterator.

Collection::offsetSet	(	$	offset,
		$	value
	)

Reimplemented in Collection_Iterator.

Collection::offsetUnset ( $ offset )

Reimplemented in Collection_Iterator.

Collection::prefetch	(	$	limit = `false`,
		$	start = `false`
	)

Items will be prefetched (if needed) in a batch for later retrieval.

Parameters:

Number	of items to prefetch or false
Start	of the prefetch or false for current position

Returns:: boolean TRUE if prefetch was successfull, FALSE if prefetch can't be supported

Reimplemented in Collection_Filtered, Collection_Query, Collection_Iterator, KWebCollection_Objects, Collection_Outer, and KWebCollection_Links.

Collection::rewind ( )

Rewinds to the beginning.

Reimplemented in Collection_Iterator.

Collection::setOption	(	$	nameOrOptions,
		$	value = `null`
	)

Sets collection option.

Parameters:

$nameOrOptions name of the option, or hashmap of options (name=>value) to set

Returns:: Collection

Collection::toArray ( )

Collection::valid ( )

Returns item at current position, staying at the current position.

Returns true if there is data at current possition

Returns:: boolean

Reimplemented in Collection_Filtered, Collection_Query, Collection_Array, Collection_Outer, and Collection_Iterator.

Field Documentation

Collection::$options

const Collection::FIELD_ARRAY = 'array()'

Extracts all fields as array.

const Collection::FIELD_INNER = '.'

const Collection::OPT_BIDIRECTIONAL = 'bidi'

Makes some collections bidirectional through caching of results.

const Collection::OPT_FIELD_EXTRACTOR = 'fieldExtractor'

Field extraction callback cb($collection, $data, $field, $default) returning extracted values or $default.

const Collection::OPT_PREFETCH_AUTO = 'prefetch_auto'

Automatically prefetches this amount of items, as soon as the last prefetch is used up.

Not every collection supports this

const Collection::OPT_RELEASE_AUTO = 'release_auto'

Automatically releases results after this many items read.

Not every collection supports this

The documentation for this class was generated from the following file:

include/core/Collection/Collection.php

Public Member Functions

Data Fields

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation

Field Documentation