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

# PDOStatement::fetch

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

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

### Описание

public function 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() - Устанавливает режим выборки по умолчанию для объекта запроса

`↑` and `↓` to navigate • `Enter` to select • `Esc` to close • `/` to open