DataReader.php 6.85 KB
Newer Older
w  
Qiang Xue committed
1 2
<?php
/**
w  
Qiang Xue committed
3
 * DataReader class file
w  
Qiang Xue committed
4 5 6
 *
 * @author Qiang Xue <qiang.xue@gmail.com>
 * @link http://www.yiiframework.com/
w  
Qiang Xue committed
7
 * @copyright Copyright &copy; 2008-2012 Yii Software LLC
w  
Qiang Xue committed
8 9 10
 * @license http://www.yiiframework.com/license/
 */

w  
Qiang Xue committed
11 12
namespace yii\db\dao;

w  
Qiang Xue committed
13 14
use yii\db\Exception;

w  
Qiang Xue committed
15
/**
w  
Qiang Xue committed
16
 * DataReader represents a forward-only stream of rows from a query result set.
w  
Qiang Xue committed
17
 *
w  
Qiang Xue committed
18
 * To read the current row of data, call [[read]]. The method [[readAll]]
w  
Qiang Xue committed
19 20
 * returns all the rows in a single array.
 *
w  
Qiang Xue committed
21 22 23 24
 * One can also retrieve the rows of data in DataReader by using `foreach`:
 *
 * ~~~
 * foreach($reader as $row) {
w  
Qiang Xue committed
25
 *     // $row represents a row of data
w  
Qiang Xue committed
26 27 28 29
 * }
 * ~~~
 *
 * Since DataReader is a forward-only stream, you can only traverse it once.
w  
Qiang Xue committed
30 31
 *
 * It is possible to use a specific mode of data fetching by setting
w  
Qiang Xue committed
32 33
 * [[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
34 35
 *
 * @author Qiang Xue <qiang.xue@gmail.com>
w  
Qiang Xue committed
36
 * @since 2.0
w  
Qiang Xue committed
37
 */
w  
Qiang Xue committed
38
class DataReader extends \yii\base\Component implements \Iterator, \Countable
w  
Qiang Xue committed
39 40 41 42 43 44 45 46
{
	private $_statement;
	private $_closed = false;
	private $_row;
	private $_index = -1;

	/**
	 * Constructor.
w  
Qiang Xue committed
47
	 * @param Command $command the command generating the query result
w  
Qiang Xue committed
48
	 */
w  
Qiang Xue committed
49
	public function __construct(Command $command)
w  
Qiang Xue committed
50 51
	{
		$this->_statement = $command->getPdoStatement();
w  
Qiang Xue committed
52
		$this->_statement->setFetchMode(\PDO::FETCH_ASSOC);
w  
Qiang Xue committed
53 54 55 56 57 58 59 60 61 62 63 64 65 66 67
	}

	/**
	 * 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.
	 * @param mixed $column Number of the column (1-indexed) or name of the column
	 * 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
68
		if ($dataType === null) {
w  
Qiang Xue committed
69
			$this->_statement->bindColumn($column, $value);
w  
Qiang Xue committed
70 71
		}
		else {
w  
Qiang Xue committed
72
			$this->_statement->bindColumn($column, $value, $dataType);
w  
Qiang Xue committed
73
		}
w  
Qiang Xue committed
74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134
	}

	/**
	 * Set the default fetch mode for this statement
	 * @param mixed $mode fetch mode
	 * @see http://www.php.net/manual/en/function.PDOStatement-setFetchMode.php
	 */
	public function setFetchMode($mode)
	{
		$params = func_get_args();
		call_user_func_array(array($this->_statement, 'setFetchMode'), $params);
	}

	/**
	 * Advances the reader to the next row in a result set.
	 * @return array|false the current row, false if no more row available
	 */
	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
	 * @return mixed|false the column of the current row, false if no more row available
	 */
	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
	 * @return mixed|false the populated object, false if no more row of data available
	 */
	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
135
		if (($result = $this->_statement->nextRowset()) !== false) {
w  
Qiang Xue committed
136
			$this->_index = -1;
w  
Qiang Xue committed
137
		}
w  
Qiang Xue committed
138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 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
		return $result;
	}

	/**
	 * Closes the reader.
	 * This frees up the resources allocated for executing this SQL statement.
	 * Read attemps after this method call are unpredictable.
	 */
	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.
w  
Qiang Xue committed
197
	 * @throws Exception if this method is invoked twice
w  
Qiang Xue committed
198 199 200
	 */
	public function rewind()
	{
w  
Qiang Xue committed
201
		if ($this->_index < 0) {
w  
Qiang Xue committed
202 203 204
			$this->_row = $this->_statement->fetch();
			$this->_index = 0;
		}
w  
Qiang Xue committed
205 206 207
		else {
			throw new Exception('DataReader cannot rewind. It is a forward-only reader.');
		}
w  
Qiang Xue committed
208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 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
	}

	/**
	 * 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;
	}
}