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.
while (($row = $stmt->fetch(PDO::FETCH_ASSOC)) !== false) { echo $row['name'], "\n"; }
Try it
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.
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
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
falsestrictly. Use!== falseor the plainwhile ($row = $stmt->fetch()). A row is a non-empty array or an object, so both are safe, but always compare withfalsewhen you handle a single-row lookup. - Default mode. Without any setting you get
FETCH_BOTH, which doubles every column. SetPDO::ATTR_DEFAULT_FETCH_MODEonce on the connection, usually toPDO::FETCH_ASSOC. - Duplicate column names overwrite each other in
FETCH_ASSOC; give columns aliases or useFETCH_NAMED. FETCH_CLASSfills properties before the constructor runs, unless you combine it withPDO::FETCH_PROPS_LATE. Prefer simple classes with public properties, or build objects yourself fromFETCH_ASSOCrows.- Native types. For SQLite and for MySQL with native prepares, integers and floats come back as PHP
intandfloat. 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 usefetchAll(), which is simpler but loads everything into memory. - A statement can be read only once (forward-only). To read it again, run
execute()again.