PDOStatement::fetch

Fetches the next row from a result set

&reftitle.description; public `mixed` `PDOStatement::fetch` `int` `fetch_style` `int` `cursor_orientation` PDO::FETCH_ORI_NEXT `int` `cursor_offset` 0

Fetches a row from a result set associated with a PDOStatement object. The `fetch_style` parameter determines how PDO returns the row.

&reftitle.parameters;

`fetch_style`

- Controls how the next row will be returned to the caller. This value must be one of the `PDO::FETCH_*` constants, defaulting to value of `PDO::ATTR_DEFAULT_FETCH_MODE` (which defaults to `PDO::FETCH_BOTH`).

  - `PDO::FETCH_ASSOC`: returns an array indexed by column name as returned in your result set

  - `PDO::FETCH_BOTH` (default): returns an array indexed by both column name and 0-indexed column number as returned in your result set

  - `PDO::FETCH_BOUND`: returns &true; and assigns the values of the columns in your result set to the PHP variables to which they were bound with the `PDOStatement::bindColumn` method

  - `PDO::FETCH_CLASS`: returns a new instance of the requested class, mapping the columns of the result set to named properties in the class. If `fetch_style` includes PDO::FETCH_CLASSTYPE (e.g. `PDO::FETCH_CLASS | PDO::FETCH_CLASSTYPE`) then the name of the class is determined from a value of the first column.

  - `PDO::FETCH_INTO`: updates an existing instance of the requested class, mapping the columns of the result set to named properties in the class

  - `PDO::FETCH_LAZY`: combines `PDO::FETCH_BOTH` and `PDO::FETCH_OBJ`, creating the object variable names as they are accessed

  - `PDO::FETCH_NUM`: returns an array indexed by column number as returned in your result set, starting at column 0

  - `PDO::FETCH_OBJ`: returns an anonymous object with property names that correspond to the column names returned in your result set

`cursor_orientation`

- For a PDOStatement object representing a scrollable cursor, this value determines which row will be returned to the caller. This value must be one of the `PDO::FETCH_ORI_*` constants, defaulting to `PDO::FETCH_ORI_NEXT`. To request a scrollable cursor for your PDOStatement object, you must set the `PDO::ATTR_CURSOR` attribute to `PDO::CURSOR_SCROLL` when you prepare the SQL statement with `PDO::prepare`.

`offset`

- For a PDOStatement object representing a scrollable cursor for which the `cursor_orientation` parameter is set to `PDO::FETCH_ORI_ABS`, this value specifies the absolute number of the row in the result set that shall be fetched.

  For a PDOStatement object representing a scrollable cursor for which the `cursor_orientation` parameter is set to `PDO::FETCH_ORI_REL`, this value specifies the row to fetch relative to the cursor position before `PDOStatement::fetch` was called.

&reftitle.returnvalues;

The return value of this function on success depends on the fetch type. In all cases, &false; is returned on failure.

&reftitle.examples;

### Fetching rows using different fetch styles

    <?php
    $sth = $dbh->prepare("SELECT name, colour FROM fruit");
    $sth->execute();

    /* Exercise PDOStatement::fetch styles */
    print("PDO::FETCH_ASSOC: ");
    print("Return next row as an array indexed by column name\n");
    $result = $sth->fetch(PDO::FETCH_ASSOC);
    print_r($result);
    print("\n");

    print("PDO::FETCH_BOTH: ");
    print("Return next row as an array indexed by both column name and number\n");
    $result = $sth->fetch(PDO::FETCH_BOTH);
    print_r($result);
    print("\n");

    print("PDO::FETCH_LAZY: ");
    print("Return next row as an anonymous object with column names as properties\n");
    $result = $sth->fetch(PDO::FETCH_LAZY);
    print_r($result);
    print("\n");

    print("PDO::FETCH_OBJ: ");
    print("Return next row as an anonymous object with column names as properties\n");
    $result = $sth->fetch(PDO::FETCH_OBJ);
    print $result->NAME;
    print("\n");
    ?>

&example.outputs;

    PDO::FETCH_ASSOC: Return next row as an array indexed by column name
    Array
    (
        [NAME] => apple
        [COLOUR] => red
    )

    PDO::FETCH_BOTH: Return next row as an array indexed by both column name and number
    Array
    (
        [NAME] => banana
        [0] => banana
        [COLOUR] => yellow
        [1] => yellow
    )

    PDO::FETCH_LAZY: Return next row as an anonymous object with column names as properties
    PDORow Object
    (
        [NAME] => orange
        [COLOUR] => orange
    )

    PDO::FETCH_OBJ: Return next row as an anonymous object with column names as properties
    kiwi

### Fetching rows with a scrollable cursor

    <?php
    function readDataForwards($dbh) {
      $sql = 'SELECT hand, won, bet FROM mynumbers ORDER BY BET';
      try {
        $stmt = $dbh->prepare($sql, array(PDO::ATTR_CURSOR => PDO::CURSOR_SCROLL));
        $stmt->execute();
        while ($row = $stmt->fetch(PDO::FETCH_NUM, PDO::FETCH_ORI_NEXT)) {
          $data = $row[0] . "\t" . $row[1] . "\t" . $row[2] . "\n";
          print $data;
        }
        $stmt = null;
      }
      catch (PDOException $e) {
        print $e->getMessage();
      }
    }
    function readDataBackwards($dbh) {
      $sql = 'SELECT hand, won, bet FROM mynumbers ORDER BY bet';
      try {
        $stmt = $dbh->prepare($sql, array(PDO::ATTR_CURSOR => PDO::CURSOR_SCROLL));
        $stmt->execute();
        $row = $stmt->fetch(PDO::FETCH_NUM, PDO::FETCH_ORI_LAST);
        do {
          $data = $row[0] . "\t" . $row[1] . "\t" . $row[2] . "\n";
          print $data;
        } while ($row = $stmt->fetch(PDO::FETCH_NUM, PDO::FETCH_ORI_PRIOR));
        $stmt = null;
      }
      catch (PDOException $e) {
        print $e->getMessage();
      }
    }

    print "Reading forwards:\n";
    readDataForwards($conn);

    print "Reading backwards:\n";
    readDataBackwards($conn);
    ?>

&example.outputs;

    Reading forwards:
    21    10    5
    16    0     5
    19    20    10

    Reading backwards:
    19    20    10
    16    0     5
    21    10    5

&reftitle.seealso;

- `PDO::prepare`
- `PDOStatement::execute`
- `PDOStatement::fetchAll`
- `PDOStatement::fetchColumn`
- `PDOStatement::fetchObject`
- `PDOStatement::setFetchMode`