[Summary view] [Print] [Text view]

   1  <?php
   2  /**
   3   * Part of the Joomla Framework Database Package
   4   *
   5   * @copyright  Copyright (C) 2005 - 2021 Open Source Matters, Inc. All rights reserved.
   6   * @license    GNU General Public License version 2 or later; see LICENSE
   7   */
   8  
   9  namespace Joomla\Database;
  10  
  11  /**
  12   * Joomla Framework Database Driver Class
  13   *
  14   * @since  1.0
  15   */
  16  class DatabaseIterator implements \Countable, \Iterator
  17  {
  18      /**
  19       * The class of object to create.
  20       *
  21       * @var    string
  22       * @since  1.0
  23       */
  24      protected $class;
  25  
  26      /**
  27       * The name of the column to use for the key of the database record.
  28       *
  29       * @var    mixed
  30       * @since  1.0
  31       */
  32      private $column;
  33  
  34      /**
  35       * The current database record.
  36       *
  37       * @var    mixed
  38       * @since  1.0
  39       */
  40      private $current;
  41  
  42      /**
  43       * A numeric or string key for the current database record.
  44       *
  45       * @var    scalar
  46       * @since  1.0
  47       */
  48      private $key;
  49  
  50      /**
  51       * The number of fetched records.
  52       *
  53       * @var    integer
  54       * @since  1.0
  55       */
  56      private $fetched = 0;
  57  
  58      /**
  59       * The statement holding the result set to iterate.
  60       *
  61       * @var    StatementInterface
  62       * @since  1.0
  63       */
  64      protected $statement;
  65  
  66      /**
  67       * Database iterator constructor.
  68       *
  69       * @param   StatementInterface  $statement  The statement holding the result set to iterate.
  70       * @param   string              $column     An option column to use as the iterator key.
  71       * @param   string              $class      The class of object that is returned.
  72       *
  73       * @since   1.0
  74       * @throws  \InvalidArgumentException
  75       */
  76  	public function __construct(StatementInterface $statement, $column = null, $class = \stdClass::class)
  77      {
  78          if (!class_exists($class))
  79          {
  80              throw new \InvalidArgumentException(sprintf('new %s(*%s*, cursor)', \get_class($this), \gettype($class)));
  81          }
  82  
  83          if ($statement)
  84          {
  85              $fetchMode = $class === \stdClass::class ? FetchMode::STANDARD_OBJECT : FetchMode::CUSTOM_OBJECT;
  86  
  87              // PDO doesn't allow extra arguments for \PDO::FETCH_CLASS, so only forward the class for the custom object mode
  88              if ($fetchMode === FetchMode::STANDARD_OBJECT)
  89              {
  90                  $statement->setFetchMode($fetchMode);
  91              }
  92              else
  93              {
  94                  $statement->setFetchMode($fetchMode, $class);
  95              }
  96          }
  97  
  98          $this->statement = $statement;
  99          $this->class     = $class;
 100          $this->column    = $column;
 101          $this->fetched   = 0;
 102          $this->next();
 103      }
 104  
 105      /**
 106       * Database iterator destructor.
 107       *
 108       * @since   1.0
 109       */
 110  	public function __destruct()
 111      {
 112          if ($this->statement)
 113          {
 114              $this->freeResult();
 115          }
 116      }
 117  
 118      /**
 119       * Get the number of rows in the result set for the executed SQL given by the cursor.
 120       *
 121       * @return  integer  The number of rows in the result set.
 122       *
 123       * @see     Countable::count()
 124       * @since   1.0
 125       */
 126      #[\ReturnTypeWillChange]
 127  	public function count()
 128      {
 129          if ($this->statement)
 130          {
 131              return $this->statement->rowCount();
 132          }
 133  
 134          return 0;
 135      }
 136  
 137      /**
 138       * The current element in the iterator.
 139       *
 140       * @return  object
 141       *
 142       * @see     Iterator::current()
 143       * @since   1.0
 144       */
 145      #[\ReturnTypeWillChange]
 146  	public function current()
 147      {
 148          return $this->current;
 149      }
 150  
 151      /**
 152       * The key of the current element in the iterator.
 153       *
 154       * @return  scalar
 155       *
 156       * @see     Iterator::key()
 157       * @since   1.0
 158       */
 159      #[\ReturnTypeWillChange]
 160  	public function key()
 161      {
 162          return $this->key;
 163      }
 164  
 165      /**
 166       * Moves forward to the next result from the SQL query.
 167       *
 168       * @return  void
 169       *
 170       * @see     Iterator::next()
 171       * @since   1.0
 172       */
 173      #[\ReturnTypeWillChange]
 174  	public function next()
 175      {
 176          // Set the default key as being the number of fetched object
 177          $this->key = $this->fetched;
 178  
 179          // Try to get an object
 180          $this->current = $this->fetchObject();
 181  
 182          // If an object has been found
 183          if ($this->current)
 184          {
 185              // Set the key as being the indexed column (if it exists)
 186              if ($this->column && isset($this->current->{$this->column}))
 187              {
 188                  $this->key = $this->current->{$this->column};
 189              }
 190  
 191              // Update the number of fetched object
 192              $this->fetched++;
 193          }
 194      }
 195  
 196      /**
 197       * Rewinds the iterator.
 198       *
 199       * This iterator cannot be rewound.
 200       *
 201       * @return  void
 202       *
 203       * @see     Iterator::rewind()
 204       * @since   1.0
 205       */
 206      #[\ReturnTypeWillChange]
 207  	public function rewind()
 208      {
 209      }
 210  
 211      /**
 212       * Checks if the current position of the iterator is valid.
 213       *
 214       * @return  boolean
 215       *
 216       * @see     Iterator::valid()
 217       * @since   1.0
 218       */
 219      #[\ReturnTypeWillChange]
 220  	public function valid()
 221      {
 222          return (boolean) $this->current;
 223      }
 224  
 225      /**
 226       * Method to fetch a row from the result set cursor as an object.
 227       *
 228       * @return  mixed  Either the next row from the result set or false if there are no more rows.
 229       *
 230       * @since   1.0
 231       */
 232  	protected function fetchObject()
 233      {
 234          if ($this->statement)
 235          {
 236              return $this->statement->fetch();
 237          }
 238  
 239          return false;
 240      }
 241  
 242      /**
 243       * Method to free up the memory used for the result set.
 244       *
 245       * @return  void
 246       *
 247       * @since   1.0
 248       */
 249  	protected function freeResult()
 250      {
 251          if ($this->statement)
 252          {
 253              $this->statement->closeCursor();
 254          }
 255      }
 256  }