RecordSetsΒΆ
There are two different ways to iterate over a recordset: an iterator or an array. In addition, there are several ways to represent each row type. Each of these permutations is given its own method.
The methods are named after the following conventions:
- fetch returns data as an array. e.g., fetchAll() returns the complete recordset as an array of associative arrays.
- get*Iterator returns an iterator that returns one row at a time. This is the best way to get data if you simply need to process records.
- The “default” row type is an associative array. e.g., fetchRow will return an associative array (keys are the names of the columns), and getIterator() returns an iterator that iterates over associative arrays.
- The Array row type is always an _indexed_ row. e.g., fetchRowAsArray will return an indexed array (integer keys).
- The “keyed” methods return some sort of associative array where the key comes from data in the column. That keyed value is removed from the row. If ther are no more columns left, then the true is used for the value. If there is exactly one column left, then it is used as the value. If there are two or more columns left, then the value becomes an associative array. e.g., “SELECT n” would result in [1 => true, 2 => true]. “SELECT n,en” would be [1 => 'one', 2 => 'two']. “SELECT n,en,sp” would be [1 => ['en' => 'one', 'sp' => 'uno'], 2 => ['en' => 'two', 'sp' => 'dos']]
The following table lists the names of the methods:
| Traverse Type | Key | Row Type | Method |
|---|---|---|---|
| array | indexed | associative | fetchAll() |
| array | indexed | index | fetchAllAsArray() |
| array | indexed | callback | fetchAllWithCallback($cb) |
| array | indexed | scalar | fetchColumn($i = 0) |
| array | associative | associative | fetchKeyed($key = '') |
| array | associative | index | fetchKeyedAsArray($key = '') |
| array | associative | callback | fetchKeyedWithCallback($cb, $key = '') |
| iterator | indexed | associative | getIterator() |
| iterator | indexed | index | getArrayIterator() |
| iterator | indexed | callback | getCallbackIterator($cb) |
| iterator | indexed | scalar | getColumnIterator($i = 0) |
| iterator | associative | associative | getKeyedIterator($key = '') |
| iterator | associative | index | getKeyedArrayIterator($key = '') |
| iterator | associative | callback | getKeyedCallbackIterator($cb, $key = '') |
If using an iterator, the following methods can be used to access the next row:
| Type | Row Type | Method |
|---|---|---|
| Return by value | One value from single row | fetchValue($i = 0) |
| Return by value | Associative array | fetchRow() |
| Return by value | Indexed array | fetchRowAsArray() |
| Modify by reference | Associative array | fetchRowInto(&$array) |
| Modify by reference | Indexed array | fetchRowIntoArray(&$array) |
| Modify by reference | Object | fetchRowIntoObject(&object) |
Note that there is no way to directly return an object. This introduces complexities (constructor parameters, injecting dependencies, etc) that are better handled by a callback. (Fetching into an object works by assuming that the object has public properties with the same name as the columns.)
The following illustrates using a callback to handle custom object creation:
$cb = function (array $row) {
return MyObject::fromArray($row);
};
foreach ($st->getCallbackIterator($cb) as $myObject)
{
echo $myObject->someProperty, PHP_EOL;
}