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;