1. <?php
  2. /**
  3.  * File containing the ezcPersistentFindIterator class
  4.  *
  5.  * @package PersistentObject
  6.  * @version 1.3.4
  7.  * @copyright Copyright (C) 2005-2007 eZ systems as. All rights reserved.
  8.  * @license http://ez.no/licenses/new_bsd New BSD License
  9.  */
 10.  
 11. /**
 12.  * This class provides functionality to iterate over a database
 13.  * result set in the form of persistent objects.
 14.  *
 15.  * ezcPersistentFindIterator only instantiates one object which
 16.  * is reused for each iteration. This saves memory and is faster
 17.  * than fetching and instantiating the result set in one go.
 18.  *
 19.  * You must loop over the complete resultset of the iterator or
 20.  * flush it before executing new queries.
 21.  *
 22.  * Example:
 23.  * <code>
 24.  *  $q = $session->createFindQuery( 'Person' );
 25.  *  $q->where( $q->expr->gt( 'age', $q->bindValue( 15 ) ) )
 26.  *    ->orderBy( 'name' )
 27.  *    ->limit( 10 );
 28.  *  $objects = $session->findIterator( $q, 'Person' );
 29.  *
 30.  *  foreach ( $objects as $object )
 31.  *  {
 32.  *     if ( ... )
 33.  *     {
 34.  *        $objects->flush();
 35.  *        break;
 36.  *     }
 37.  *  }
 38.  * </code>
 39.  *
 40.  * @version 1.3.4
 41.  * @package PersistentObject
 42.  */
 43. class ezcPersistentFindIterator implements Iterator
 44. {
 45.     /**
 46.      * Stores the current object of the iterator.
 47.      *
 48.      * This variable is null if there is no current object.
 49.      *
 50.      * @var object 
 51.      */
 52.     private $object = null;
 53.  
 54.     /**
 55.      * The statement to retrieve data from.
 56.      *
 57.      * @var PDOStatement 
 58.      */
 59.     private $stmt = null;
 60.  
 61.     /**
 62.      * The definition of the persistent object type.
 63.      *
 64.      * $var ezcPersistentObjectDefinition
 65.      */
 66.     private $def = null;
 67.  
 68.     /**
 69.      * Initializes the iterator with the statement $stmt and the definition $def..
 70.      *
 71.      * The statement $stmt must be executed but not used to retrieve any results yet.
 72.      * The iterator will return objects with they persistent object type provided by
 73.      * $def.
 74.      * @param PDOStatement $stmt 
 75.      * @param ezcPersistentObjectDefinition $def 
 76.      */
 77.     public function __construct( PDOStatement $stmt, ezcPersistentObjectDefinition $def )
 78.     {
 79.         $this->stmt = $stmt;
 80.         $this->def = $def;
 81.     }
 82.  
 83.     /**
 84.      * Sets the iterator to point to the first object in the result set.
 85.      *
 86.      * @return void 
 87.      */
 88.     public function rewind()
 89.     {
 90.         if ( $this->object === null )
 91.         {
 92.             $this->next();
 93.         }
 94.     }
 95.  
 96.     /**
 97.      * Returns the current object of this iterator.
 98.      *
 99.      * Returns null if there is no current object.
100.      *
101.      * @return object 
102.      */
103.     public function current()
104.     {
105.         return $this->object;
106.     }
107.  
108.     /**
109.      * Returns null.
110.      *
111.      * Persistent objects do not have a key. Hence, this method always returns
112.      * null.
113.      *
114.      * @return null 
115.      */
116.     public function key()
117.     {
118.         return null;
119.     }
120.  
121.     /**
122.      * Returns the next persistent object in the result set.
123.      *
124.      * The next object is set to the current object of the iterator.
125.      * Returns null and sets the current object to null if there
126.      * are no more results in the result set.
127.      *
128.      * @return object 
129.      */
130.     public function next()
131.     {
132.         $row = false;
133.         try
134.         {
135.             $row = $this->stmt->fetch( PDO::FETCH_ASSOC );
136.         }
137.         catch ( PDOException $e ) // MySQL 5.0 throws this if the statement is not executed.
138.         {
139.             $this->object = null;
140.             return;
141.         }
142.  
143.         // SQLite returns empty array on faulty statement!
144.         if ( $row !== false && ( is_array( $row ) && sizeof( $row ) != 0 ) && $this->checkDef() )
145.         {
146.             if ( $this->object == null ) // no object yet
147.             {
148.                 $this->object = new $this->def->class;
149.             }
150.             $this->object->setState( ezcPersistentStateTransformer::rowToStateArray( $row, $this->def ) );
151.         }
152.         else // no more objects in the result set
153.         {
154.             $this->object = null;
155.         }
156.         return $this->object;
157.     }
158.  
159.     /**
160.      * Checks if the persistence defintion contains at least a table and a
161.      * class name.
162.      *
163.      * @return bool 
164.      */
165.     private function checkDef()
166.     {
167.         return $this->def->class !== null && $this->def->table !== null;
168.     }
169.  
170.     /**
171.      * Returns true if there is a current object.
172.      *
173.      * @return bool 
174.      */
175.     public function valid()
176.     {
177.         return $this->object !== null ? true : false;
178.     }
179.  
180.     /**
181.      * Clears the results from the iterator.
182.      *
183.      * This method must be called if you decide not to iterate over the complete resultset.
184.      * Failure to do so may result in errors on subsequent SQL queries.
185.      *
186.      * @return void 
187.      */
188.     public function flush()
189.     {
190.         $this->stmt->closeCursor();
191.     }
192. }
193. ?>