/**
* Returns the result of $query for the $class as an iterator.
*
* This method is similar to {@link find()} but returns an {@link
* ezcPersistentIdentityFindIterator} instead of an array of objects. This
* is useful if you are going to loop over the objects and just need them
* one at the time. Because you only instantiate one object it is faster
* than {@link find()}. In addition, only 1 record is retrieved from the
* database in each iteration, which may reduce the data transfered between
* the database and PHP, if you iterate only through a small subset of the
* affected records.
*
* Note that if you do not loop over the complete result set you must call
* {@link ezcPersistentFindIterator::flush()} before issuing another query.
*
* The find interator will automatically look up result objects in the
* identity map and return existing identities, if they have already been
* recorded.
*
* @throws ezcPersistentDefinitionNotFoundException
* if there is no such persistent class.
* @throws ezcPersistentQueryException
* if the find query failed.
* @throws ezcBaseValueException
* if $query parameter is not an instance of ezcPersistentFindQuery
* or ezcQuerySelect. Or if $class is missing if you use
* ezcQuerySelect.
*
* @param ezcPersistentFindQuery|ezcQuerySelect $query
* @param string $class
*
* @return ezcPersistentIdentityFindIterator
* @apichange This method will only accept an instance of
* ezcPersistentFindQuery as the $query parameter in future
* major releases. The $class parameter will be removed.
*/
public function findIterator($query, $class = null)
{
// Sanity checks
if (!is_object($query) || !$query instanceof ezcPersistentFindQuery && !$query instanceof ezcQuerySelect) {
throw new ezcBaseValueException('query', $query, 'ezcPersistentFindQuery (or ezcQuerySelect)');
}
if ($query instanceof ezcQuerySelect && $class === null) {
throw new ezcBaseValueException('class', $class, 'string (mandatory, if ezcQuerySelect is used)');
}
// Extract class name and select query form parameter
if ($query instanceof ezcPersistentFindQuery) {
$class = $query->className;
$query = $query->query;
}
$def = $this->definitionManager->fetchDefinition($class);
$stmt = $this->session->performQuery($query);
return new ezcPersistentIdentityFindIterator($stmt, $def, $this->identityMap, $this->properties['options']);
}
