Skip to content
Tutorials Center
My learning

Topics

PHP Reference ยท Databases (PDO)

PHP PDOStatement::fetch() method

Reference for PHP PDOStatement::fetch(): read one row at a time, choose between FETCH_ASSOC, NUM, OBJ, CLASS and NAMED, and handle the false result at the end.

PDOStatement::fetch() returns the next row of a result set and moves the cursor forward. Call it in a while loop to walk through a result one row at a time, or once when you expect a single row, such as a lookup by primary key.

The shape of the row depends on the fetch mode: an associative array, a numbered list, an object, an instance of your own class and more. When no rows are left, fetch() returns false.

PHP
while (($row = $stmt->fetch(PDO::FETCH_ASSOC)) !== false) {
    echo $row['name'], "\n";
}

Try it

PHP Fetch modes side by side

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with fgets(STDIN)), it gets the next line from this box.

PHP Fetching into your own class

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with fgets(STDIN)), it gets the next line from this box.

Syntax

PHP
PDOStatement::fetch(
    int $mode = PDO::FETCH_DEFAULT,
    int $cursorOrientation = PDO::FETCH_ORI_NEXT,
    int $cursorOffset = 0
): mixed
Name Description
$mode How to shape the row. If omitted, the statement's mode (set with setFetchMode()) or the connection's PDO::ATTR_DEFAULT_FETCH_MODE is used; the built-in default is PDO::FETCH_BOTH.
$cursorOrientation Which row to read when the cursor is scrollable. Rarely used; the default is the next row.
$cursorOffset The row offset for relative or absolute orientation.

Common modes:

Mode Result
PDO::FETCH_ASSOC ['id' => 1, 'name' => 'Mia']
PDO::FETCH_NUM [1, 'Mia']
PDO::FETCH_BOTH Both of the above in one array (every value twice).
PDO::FETCH_OBJ An anonymous stdClass with a property per column.
PDO::FETCH_CLASS A new object of a class you name; properties are filled from the columns.
PDO::FETCH_NAMED Like ASSOC, but a repeated column name becomes an array of values.
PDO::FETCH_LAZY An object that builds properties on access.
PDO::FETCH_BOUND Returns true and writes values into variables set up with bindColumn().

Return value: the row in the requested shape, or false when there are no more rows. false is also returned on failure when the error mode is not exception mode.

Errors / Exceptions: PDOException (in exception mode) if the fetch fails, for example when the statement was never executed or returned no result set.

Usage notes

  • Test for false strictly. Use !== false or the plain while ($row = $stmt->fetch()). A row is a non-empty array or an object, so both are safe, but always compare with false when you handle a single-row lookup.
  • Default mode. Without any setting you get FETCH_BOTH, which doubles every column. Set PDO::ATTR_DEFAULT_FETCH_MODE once on the connection, usually to PDO::FETCH_ASSOC.
  • Duplicate column names overwrite each other in FETCH_ASSOC; give columns aliases or use FETCH_NAMED.
  • FETCH_CLASS fills properties before the constructor runs, unless you combine it with PDO::FETCH_PROPS_LATE. Prefer simple classes with public properties, or build objects yourself from FETCH_ASSOC rows.
  • Native types. For SQLite and for MySQL with native prepares, integers and floats come back as PHP int and float. With MySQL emulated prepares they may arrive as strings.
  • One row or many? For a single value use fetchColumn(). To collect all rows at once use fetchAll(), which is simpler but loads everything into memory.
  • A statement can be read only once (forward-only). To read it again, run execute() again.