PDOStatement::fetch

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.1.0)

PDOStatement::fetch — Извлекает следующую строку из результирующего набора

Описание

public PDOStatement::fetch(int $mode = PDO::FETCH_DEFAULT, int $cursorOrientation = PDO::FETCH_ORI_NEXT, int $cursorOffset = 0): mixed

Метод извлекает следующую строку из результирующего набора объекта PDOStatement. Параметр mode определяет, в каком виде модуль PDO вернёт эту строку.

Список параметров

mode

Параметр определяет, в каком виде следующая строка вернётся в вызывающий метод. Параметр принимает значение в виде константы семейства PDO::FETCH_*. Значение по умолчанию равняется PDO::ATTR_DEFAULT_FETCH_MODE, что равносильно значению PDO::FETCH_BOTH.

PDO::FETCH_ASSOC: возвращает массив, индексированный именами столбцов результирующего набора
PDO::FETCH_BOTH (по умолчанию): возвращает массив, индексированный названиями столбцов результирующего набора, и их номерами начиная с 0
PDO::FETCH_BOUND: возвращает true и присваивает значения столбцов результирующего набора PHP-переменным, которые привязали к этим столбцам методом PDOStatement::bindColumn()
PDO::FETCH_CLASS: возвращает новый экземпляр запрошенного класса. Объект инициализируется путём сопоставления столбцов из набора с результатами запроса со свойствами класса. Столбцы сопоставляются до вызова конструктора, что разрешает заполнять свойства независимо от видимости или установки модификатора readonly. PHP вызовет магический метод __set(), если класс не содержит свойства с таким названием и если метод определили в классе; иначе в объекте создаётся динамическое открытое свойство. Однако при установке флага PDO::FETCH_PROPS_LATE конструктор вызывается до заполнения свойств. При передаче в параметр mode флага PDO::FETCH_CLASSTYPE в аргументе наподобие PDO::FETCH_CLASS | PDO::FETCH_CLASSTYPE название класса определяется из значения первого столбца.
PDO::FETCH_INTO: обновляет существующий объект запрошенного класса, присваивая значения столбцов результирующего набора именованным свойствам объекта.
PDO::FETCH_LAZY: комбинирует PDO::FETCH_BOTH и PDO::FETCH_OBJ и возвращает объект PDORow, который создаёт имена свойств объекта по мере доступа к ним.
PDO::FETCH_NAMED: возвращает массив в той же форме, в какой его возвращает флаг PDO::FETCH_ASSOC, но если в наборе с результатами запроса содержатся столбцы с одинаковым названием, значением, на который ссылается ключ, станет массив значений строки, которые содержатся в столбцах с этим названием.
PDO::FETCH_NUM: возвращает массив, индексированный номерами столбцов (начиная с 0)
PDO::FETCH_OBJ: создаёт анонимный объект со свойствами, соответствующими именам столбцов результирующего набора
PDO::FETCH_PROPS_LATE: если используется с PDO::FETCH_CLASS, конструктор класса будет вызван перед назначением свойств из значений столбцов.

cursorOrientation

Для объектов PDOStatement представляющих прокручиваемый курсор, этот параметр определяет, какая строка будет возвращаться в вызывающий метод. Значением параметра должна быть одна из констант PDO::FETCH_ORI_*, по умолчанию PDO::FETCH_ORI_NEXT. Чтобы запросить прокручиваемый курсор для запроса PDOStatement, необходимо задать атрибут PDO::ATTR_CURSOR со значением PDO::CURSOR_SCROLL во время подготовки запроса методом PDO::prepare().

cursorOffset

Для объектов PDOStatement, представляющих прокручиваемый курсор, параметр cursorOrientation которых принимает значение PDO::FETCH_ORI_ABS, эта величина означает абсолютный номер строки, которую необходимо извлечь из результирующего набора.

Для объектов PDOStatement, представляющих прокручиваемый курсор, параметр cursorOrientation которых принимает значение PDO::FETCH_ORI_REL, эта величина указывает, какая строка относительно текущего положения курсора будет извлечена функцией PDOStatement::fetch().

Возвращаемые значения

Значение возврата зависит от режима выборки, когда функция выполнилась успешно. Функция возвращает false, если возникла ошибка или не осталось строк.

Ошибки

Метод выдаёт ошибку уровня E_WARNING, если для атрибута PDO::ATTR_ERRMODE установили режим PDO::ERRMODE_WARNING.

Метод выбрасывает исключение PDOException, если для атрибута PDO::ATTR_ERRMODE установили режим PDO::ERRMODE_EXCEPTION.

Примеры

Пример #1 Извлечение строк в разных режимах выборки

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

/* Примеры различных режимов работы PDOStatement::fetch */
print "PDO::FETCH_ASSOC: ";
print "Возвращаем следующую строку в виде массива, индексированного именами столбцов\n";
$result = $sth->fetch(PDO::FETCH_ASSOC);
print_r($result);
print "\n";

print "PDO::FETCH_BOTH: ";
print "Возвращаем следующую строку в виде массива, индексированного как именами столбцов, так и их номерами\n";
$result = $sth->fetch(PDO::FETCH_BOTH);
print_r($result);
print "\n";

print "PDO::FETCH_LAZY: ";
print "Возвращаем следующую строку в виде объекта класса PDORow с именами столбцов в качестве свойств\n";
$result = $sth->fetch(PDO::FETCH_LAZY);
print_r($result);
print "\n";

print "PDO::FETCH_OBJ: ";
print "Возвращаем следующую строку в виде анонимного объекта со свойствами, соответствующими столбцам\n";
$result = $sth->fetch(PDO::FETCH_OBJ);
print $result->name;
print "\n";
?>

Результат выполнения приведённого примера:

PDO::FETCH_ASSOC: Возвращаем следующую строку в виде массива, индексированного именами столбцов
Array
(
    [name] => apple
    [colour] => red
)

PDO::FETCH_BOTH: Возвращаем следующую строку в виде массива, индексированного как именами столбцов, так и их номерами
Array
(
    [name] => banana
    [0] => banana
    [colour] => yellow
    [1] => yellow
)

PDO::FETCH_LAZY: Возвращаем следующую строку в виде анонимного объекта со свойствами, соответствующими столбцам
PDO::FETCH_LAZY: Возвращаем следующую строку в виде объекта класса PDORow с именами столбцов в качестве свойств
PDORow Object
(
    [name] => orange
    [colour] => orange
)

PDO::FETCH_OBJ: Возвращаем следующую строку в виде анонимного объекта со свойствами, соответствующими столбцам
kiwi

Пример #2 Выборка строк средствами прокручиваемого курсора

<?php
function readDataForwards($dbh) {
    $sql = 'SELECT hand, won, bet FROM mynumbers ORDER BY BET';
    $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;
    }
}
function readDataBackwards($dbh) {
    $sql = 'SELECT hand, won, bet FROM mynumbers ORDER BY bet';
    $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));
}

print "Читаем в прямой последовательности:\n";
readDataForwards($conn);

print "Читаем в обратной последовательности:\n";
readDataBackwards($conn);
?>

Результат выполнения приведённого примера:

Читаем в прямой последовательности:
21    10    5
16    0     5
19    20    10

Читаем в обратной последовательности:
19    20    10
16    0     5
21    10    5

Пример #3 Порядок конструкторов

При извлечении объектов через флаг PDO::FETCH_CLASS сначала присваиваются свойства объекта, а затем вызывается конструктор класса. Однако при одновременной передаче флага PDO::FETCH_PROPS_LATE порядок действий изменяется на противоположный: вначале вызывается конструктор, а затем присваиваются свойства.

<?php

class Person
{
    private $name;

    public function __construct()
    {
        $this->tell();
    }

    public function tell()
    {
        if (isset($this->name)) {
            echo "Меня зовут {$this->name}.\n";
        } else {
            echo "Мне ещё не дали имя.\n";
        }
    }
}

$sth = $dbh->query("SELECT * FROM people");

$sth->setFetchMode(PDO::FETCH_CLASS, 'Person');
$person = $sth->fetch();
$person->tell();

$sth->setFetchMode(PDO::FETCH_CLASS|PDO::FETCH_PROPS_LATE, 'Person');
$person = $sth->fetch();
$person->tell();

?>

Вывод приведённого примера будет похож на:

Меня зовут Alice.
Меня зовут Alice.
Мне ещё не дали имя.
Меня зовут Bob.

Смотрите также

PDO::prepare() - Подготавливает запрос к выполнению и возвращает связанный с этим запросом объект
PDOStatement::execute() - Выполняет подготовленный запрос
PDOStatement::fetchAll() - Выбирает строки, которые остались в наборе результатов
PDOStatement::fetchColumn() - Возвращает данные одного столбца следующей строки результирующего набора
PDOStatement::fetchObject() - Извлекает следующую строку и возвращает её в виде объекта
PDOStatement::setFetchMode() - Устанавливает режим выборки по умолчанию для объекта запроса