DataReader.php 7.6 KB
Newer Older
w  
Qiang Xue committed
1 2 3
<?php
/**
 * @link http://www.yiiframework.com/
Qiang Xue committed
4
 * @copyright Copyright (c) 2008 Yii Software LLC
w  
Qiang Xue committed
5 6 7
 * @license http://www.yiiframework.com/license/
 */

Qiang Xue committed
8
namespace yii\db;
w  
Qiang Xue committed
9

Qiang Xue committed
10
use yii\base\InvalidCallException;
w  
Qiang Xue committed
11

w  
Qiang Xue committed
12
/**
w  
Qiang Xue committed
13
 * DataReader represents a forward-only stream of rows from a query result set.
w  
Qiang Xue committed
14
 *
Qiang Xue committed
15 16 17
 * To read the current row of data, call [[read()]]. The method [[readAll()]]
 * returns all the rows in a single array. Rows of data can also be read by
 * iterating through the reader. For example,
w  
Qiang Xue committed
18 19
 *
 * ~~~
Qiang Xue committed
20 21 22 23 24 25 26
 * $reader = $command->query('SELECT * FROM tbl_post');
 *
 * while ($row = $reader->read()) {
 *     $rows[] = $row;
 * }
 *
 * // equivalent to:
resurtm committed
27
 * foreach ($reader as $row) {
Qiang Xue committed
28
 *     $rows[] = $row;
w  
Qiang Xue committed
29
 * }
Qiang Xue committed
30 31 32
 *
 * // equivalent to:
 * $rows = $reader->readAll();
w  
Qiang Xue committed
33 34
 * ~~~
 *
Qiang Xue committed
35 36
 * Note that since DataReader is a forward-only stream, you can only traverse it once.
 * Doing it the second time will throw an exception.
w  
Qiang Xue committed
37 38
 *
 * It is possible to use a specific mode of data fetching by setting
w  
Qiang Xue committed
39 40
 * [[fetchMode]]. See the [PHP manual](http://www.php.net/manual/en/function.PDOStatement-setFetchMode.php)
 * for more details about possible fetch mode.
w  
Qiang Xue committed
41
 *
42
 * @property integer $columnCount The number of columns in the result set. This property is read-only.
Carsten Brandt committed
43
 * @property integer $fetchMode Fetch mode. This property is write-only.
44 45
 * @property boolean $isClosed Whether the reader is closed or not. This property is read-only.
 * @property integer $rowCount Number of rows contained in the result. This property is read-only.
Qiang Xue committed
46
 *
w  
Qiang Xue committed
47
 * @author Qiang Xue <qiang.xue@gmail.com>
w  
Qiang Xue committed
48
 * @since 2.0
w  
Qiang Xue committed
49
 */
Qiang Xue committed
50
class DataReader extends \yii\base\Object implements \Iterator, \Countable
w  
Qiang Xue committed
51
{
Qiang Xue committed
52 53 54
	/**
	 * @var \PDOStatement the PDOStatement associated with the command
	 */
w  
Qiang Xue committed
55 56 57 58 59 60 61
	private $_statement;
	private $_closed = false;
	private $_row;
	private $_index = -1;

	/**
	 * Constructor.
w  
Qiang Xue committed
62
	 * @param Command $command the command generating the query result
Qiang Xue committed
63
	 * @param array $config name-value pairs that will be used to initialize the object properties
w  
Qiang Xue committed
64
	 */
Alexander Makarov committed
65
	public function __construct(Command $command, $config = [])
w  
Qiang Xue committed
66
	{
Qiang Xue committed
67
		$this->_statement = $command->pdoStatement;
w  
Qiang Xue committed
68
		$this->_statement->setFetchMode(\PDO::FETCH_ASSOC);
Qiang Xue committed
69
		parent::__construct($config);
w  
Qiang Xue committed
70 71 72 73 74 75
	}

	/**
	 * Binds a column to a PHP variable.
	 * When rows of data are being fetched, the corresponding column value
	 * will be set in the variable. Note, the fetch mode must include PDO::FETCH_BOUND.
76
	 * @param integer|string $column Number of the column (1-indexed) or name of the column
w  
Qiang Xue committed
77 78 79 80 81 82 83 84
	 * in the result set. If using the column name, be aware that the name
	 * should match the case of the column, as returned by the driver.
	 * @param mixed $value Name of the PHP variable to which the column will be bound.
	 * @param integer $dataType Data type of the parameter
	 * @see http://www.php.net/manual/en/function.PDOStatement-bindColumn.php
	 */
	public function bindColumn($column, &$value, $dataType = null)
	{
w  
Qiang Xue committed
85
		if ($dataType === null) {
w  
Qiang Xue committed
86
			$this->_statement->bindColumn($column, $value);
Qiang Xue committed
87
		} else {
w  
Qiang Xue committed
88
			$this->_statement->bindColumn($column, $value, $dataType);
w  
Qiang Xue committed
89
		}
w  
Qiang Xue committed
90 91 92 93
	}

	/**
	 * Set the default fetch mode for this statement
94
	 * @param integer $mode fetch mode
w  
Qiang Xue committed
95 96 97 98 99
	 * @see http://www.php.net/manual/en/function.PDOStatement-setFetchMode.php
	 */
	public function setFetchMode($mode)
	{
		$params = func_get_args();
Alexander Makarov committed
100
		call_user_func_array([$this->_statement, 'setFetchMode'], $params);
w  
Qiang Xue committed
101 102 103 104
	}

	/**
	 * Advances the reader to the next row in a result set.
105
	 * @return array the current row, false if no more row available
w  
Qiang Xue committed
106 107 108 109 110 111 112 113 114
	 */
	public function read()
	{
		return $this->_statement->fetch();
	}

	/**
	 * Returns a single column from the next row of a result set.
	 * @param integer $columnIndex zero-based column index
115
	 * @return mixed the column of the current row, false if no more rows available
w  
Qiang Xue committed
116 117 118 119 120 121 122 123 124 125
	 */
	public function readColumn($columnIndex)
	{
		return $this->_statement->fetchColumn($columnIndex);
	}

	/**
	 * Returns an object populated with the next row of data.
	 * @param string $className class name of the object to be created and populated
	 * @param array $fields Elements of this array are passed to the constructor
126
	 * @return mixed the populated object, false if no more row of data available
w  
Qiang Xue committed
127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150
	 */
	public function readObject($className, $fields)
	{
		return $this->_statement->fetchObject($className, $fields);
	}

	/**
	 * Reads the whole result set into an array.
	 * @return array the result set (each array element represents a row of data).
	 * An empty array will be returned if the result contains no row.
	 */
	public function readAll()
	{
		return $this->_statement->fetchAll();
	}

	/**
	 * Advances the reader to the next result when reading the results of a batch of statements.
	 * This method is only useful when there are multiple result sets
	 * returned by the query. Not all DBMS support this feature.
	 * @return boolean Returns true on success or false on failure.
	 */
	public function nextResult()
	{
w  
Qiang Xue committed
151
		if (($result = $this->_statement->nextRowset()) !== false) {
w  
Qiang Xue committed
152
			$this->_index = -1;
w  
Qiang Xue committed
153
		}
w  
Qiang Xue committed
154 155 156 157 158 159
		return $result;
	}

	/**
	 * Closes the reader.
	 * This frees up the resources allocated for executing this SQL statement.
160
	 * Read attempts after this method call are unpredictable.
w  
Qiang Xue committed
161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212
	 */
	public function close()
	{
		$this->_statement->closeCursor();
		$this->_closed = true;
	}

	/**
	 * whether the reader is closed or not.
	 * @return boolean whether the reader is closed or not.
	 */
	public function getIsClosed()
	{
		return $this->_closed;
	}

	/**
	 * Returns the number of rows in the result set.
	 * Note, most DBMS may not give a meaningful count.
	 * In this case, use "SELECT COUNT(*) FROM tableName" to obtain the number of rows.
	 * @return integer number of rows contained in the result.
	 */
	public function getRowCount()
	{
		return $this->_statement->rowCount();
	}

	/**
	 * Returns the number of rows in the result set.
	 * This method is required by the Countable interface.
	 * Note, most DBMS may not give a meaningful count.
	 * In this case, use "SELECT COUNT(*) FROM tableName" to obtain the number of rows.
	 * @return integer number of rows contained in the result.
	 */
	public function count()
	{
		return $this->getRowCount();
	}

	/**
	 * Returns the number of columns in the result set.
	 * Note, even there's no row in the reader, this still gives correct column number.
	 * @return integer the number of columns in the result set.
	 */
	public function getColumnCount()
	{
		return $this->_statement->columnCount();
	}

	/**
	 * Resets the iterator to the initial state.
	 * This method is required by the interface Iterator.
Qiang Xue committed
213
	 * @throws InvalidCallException if this method is invoked twice
w  
Qiang Xue committed
214 215 216
	 */
	public function rewind()
	{
w  
Qiang Xue committed
217
		if ($this->_index < 0) {
w  
Qiang Xue committed
218 219
			$this->_row = $this->_statement->fetch();
			$this->_index = 0;
Qiang Xue committed
220
		} else {
Qiang Xue committed
221
			throw new InvalidCallException('DataReader cannot rewind. It is a forward-only reader.');
w  
Qiang Xue committed
222
		}
w  
Qiang Xue committed
223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264
	}

	/**
	 * Returns the index of the current row.
	 * This method is required by the interface Iterator.
	 * @return integer the index of the current row.
	 */
	public function key()
	{
		return $this->_index;
	}

	/**
	 * Returns the current row.
	 * This method is required by the interface Iterator.
	 * @return mixed the current row.
	 */
	public function current()
	{
		return $this->_row;
	}

	/**
	 * Moves the internal pointer to the next row.
	 * This method is required by the interface Iterator.
	 */
	public function next()
	{
		$this->_row = $this->_statement->fetch();
		$this->_index++;
	}

	/**
	 * Returns whether there is a row of data at current position.
	 * This method is required by the interface Iterator.
	 * @return boolean whether there is a row of data at current position.
	 */
	public function valid()
	{
		return $this->_row !== false;
	}
}