Режимы выборки

Информацию о семействе констант курсора — PDO::FETCH_ORI_* — содержит раздел «Константы курсора».

Базовые режимы выборки

Режим выборки	Краткое описание
`PDO::FETCH_DEFAULT`	Служебный режим, в котором данные извлекаются в текущем режиме выборки по умолчанию.
`PDO::FETCH_ASSOC`	Ассоциативный массив с индексацией только по названию столбца.
`PDO::FETCH_BOTH` (режим по умолчанию)	Индексно-ассоциативный массив с индексацией как по номеру, так и по названию столбца.
`PDO::FETCH_NAMED`	Вариант режима `PDO::FETCH_ASSOC`, в котором при дублировании названий столбцов значения не перезаписываются, а возвращаются в массиве.
`PDO::FETCH_NUM`	Индексный массив с индексацией только по номеру столбца.
`PDO::FETCH_COLUMN`	Значение или массив значений одного столбца.
`PDO::FETCH_KEY_PAIR`	Массив пар «ключ — значение» с индексацией по первому столбцу.
`PDO::FETCH_FUNC`	Результат вызова callback-функции. Режим совместим только с методом PDOStatement::fetchAll().
`PDO::FETCH_OBJ`	Объект стандартного класса — stdClass.
`PDO::FETCH_CLASS`	Объект конкретного класса.

Опции режима PDO::FETCH_CLASS

Опции изменяют поведение режима PDO::FETCH_CLASS.

Опция	Краткое описание
`PDO::FETCH_CLASSTYPE`	Опция указывает вернуть данные в объекте класса, название которого совпадает с названием первого столбца в запросе.
`PDO::FETCH_PROPS_LATE`	Опция указывает вызвать конструктор перед установкой свойств объекта.
`PDO::FETCH_SERIALIZE`	Опция указывает вернуть PHP-объект из сериализованных данных. Начиная с PHP 8.1.0 опция устарела.

Режимы с одним результатом

Следующие режимы несовместимы с методом PDOStatement::fetchAll().

Режим выборки	Краткое описание
`PDO::FETCH_BOUND`	Привязывает значения к переменным.
`PDO::FETCH_INTO`	Обновляет свойства объекта.
`PDO::FETCH_LAZY`	Ленивая выборка через объект PDORow, который поддерживает доступ к свойствам как через синтаксис доступа к элементам массива, так и через стандартный синтаксис доступа к свойствам объекта.

Флаги специфичного поведения метода PDOStatement::fetchAll()

Следующие режимы работают только для многострочной выборки методом PDOStatement::fetchAll() и несовместимы с режимами выборки по другой логике. Подробности даёт полная документация.

Режим выборки	Краткое описание
`PDO::FETCH_GROUP`	Группирует результаты по первому столбцу.
`PDO::FETCH_UNIQUE`	Уникально индексирует результаты по первому столбцу.

Обработка дублирующихся названий столбцов

Результаты выборки иногда содержат столбцы с одинаковым названием, как при объединении двух таблиц с одноимёнными столбцами.

Массив или объект возвращается с единственным значением из одноимённых столбцов, поскольку PHP-структуры — массивы и объекты — не поддерживают одинаковых названий ключей или свойств.

Какое значение из дубликатов названий вернётся — не определено.

Столбцам указывают псевдонимы, чтобы проблема дублирования названий столбцов не возникала. Например:

SELECT table1.created_at AS t1_created_at,
       table2.created_at AS t2_created_at
FROM table1
JOIN table2 ON table1.table2id = table2.id

Дополнительную информацию даёт описание режимов PDO::FETCH_NAMED, PDO::ATTR_FETCH_TABLE_NAMES и PDO::ATTR_FETCH_CATALOG_NAMES.

Установка режима выборки по умолчанию

Передача константы PDO::ATTR_DEFAULT_FETCH_MODE в параметрах метода PDO::__construct() или в аргументе атрибута метода PDO::setAttribute() устанавливает режим выборки по умолчанию для всех запросов.

Режим выборки по умолчанию для конкретной SQL-инструкции устанавливают методом PDOStatement::setFetchMode(). Индивидуальный режим влияет на повторное выполнение подготовленных SQL-инструкций и перебор результатов конструкцией foreach.

Предостережение

Методом PDOStatement::setAttribute() нельзя установить режим выборки по умолчанию для конкретного запроса. Метод принимает только атрибуты, совместимые с текущим драйвером, и молча игнорирует атрибуты, которые не распознал.

PDO::FETCH_DEFAULT (int)

Режим доступен с PHP 8.0.7.

Служебное значение, которое ссылается на текущий режим выборки по умолчанию для объекта PDOStatement. Константу часто указывают как значение по умолчанию для параметров методов пользовательских классов, которые расширяют класс PDOStatement и которые указывают через атрибут PDO::ATTR_STATEMENT_CLASS как тип для возврата результатов запроса.

Значение нельзя указывать с атрибутом PDO::ATTR_DEFAULT_FETCH_MODE.

PDO::FETCH_ASSOC (int)

В режиме PDO::FETCH_ASSOC возвращается ассоциативный массив, в котором ключи соответствуют названиям столбцов.

<?php

$stmt = $pdo->query("SELECT userid, name, country FROM users");
$row = $stmt->fetch(\PDO::FETCH_ASSOC);
print_r($row);

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

Array
(
    [userid] => 104
    [name] => Chris
    [country] => Ukraine
)

PDO::FETCH_BOTH (int)

Режим выборки по умолчанию.

В режиме PDO::FETCH_BOTH возвращается индексно-ассоциативный массив, в котором значение каждой строки дублируется: одно возвращается со строковым ключом по названию столбца, другое — с числовым ключом по номеру столбца.

Нумерация столбцов начинаются с 0 и определяется порядком столбцов в результатах запроса, а не, например, порядком определения столбцов в таблице.

Замечание:
Лучше не опираться на числовой индекс столбца, поскольку нумерация изменится при изменении порядка столбцов в запросе или при изменении схемы таблицы и запросе наподобие SELECT *.

Замечание: Количество записей с индексацией по названию столбца не совпадёт с количеством записей с индексацией по номеру столбца, если в результате возвращаются столбцы с одинаковым названием.

<?php

$stmt = $pdo->query("SELECT userid, name, country FROM users");
$row = $stmt->fetch(\PDO::FETCH_BOTH);
print_r($row);

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

Array
(
    [id] => 104,
    [0] => 104,
    [name] => Chris,
    [1] => Chris,
    [country] => Ukraine,
    [2] => Ukraine
)

PDO::FETCH_NAMED (int)

В режиме PDO::FETCH_NAMED результаты возвращаются в формате, аналогичном режиму PDO::FETCH_ASSOC, за исключением возврата всех значений повторных столбцов в виде списка.

Подробнее об обработке повторных названий столбцов и альтернативах рассказывает раздел «Обработка дублирующихся названий столбцов».

Порядок возврата значений повторных столбцов не определён. Невозможно определить конкретный источник каждого значения.

<?php

$stmt = $pdo->query(
    "SELECT users.*, referrer.name
     FROM users
     LEFT JOIN users AS referrer ON users.referred_by = referrer.userid
     WHERE userid = 109"
);

$row = $stmt->fetch(\PDO::FETCH_NUM);
print_r($row);

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

Array
(
    [userid] => 109
    [name] => Array
        (
            [0] => Toni
            [1] => Chris
        )
    [country] => Germany
    [referred_by] = 104
)

PDO::FETCH_NUM (int)

В режиме PDO::FETCH_NUM возвращается индексный массив, в котором ключи соответствуют номеру столбца. Нумерация столбцов начинается с 0 и определяется порядком столбцов в результатах запроса, а не, например, порядком определения столбцов в таблице.

Замечание: Лучше не опираться на числовой индекс столбца, поскольку нумерация изменится при изменении порядка столбцов в запросе или при изменении схемы таблицы и запросе наподобие SELECT *.

<?php

$stmt = $pdo->query("SELECT userid, name, country FROM users");
$row = $stmt->fetch(\PDO::FETCH_NUM);
print_r($row);

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

Array
(
    [0] => 104
    [1] => Chris
    [2] => Ukraine
)

PDO::FETCH_COLUMN (int)

В режиме PDO::FETCH_COLUMN возвращаются значения из одного столбца. При вызове метода PDOStatement::setFetchMode() или PDOStatement::fetchAll() конкретный столбец указывают во втором аргументе.

Метод выбросит ошибку ValueError, если таблица не содержит заданный столбец.

<?php

$stmt = $pdo->query("SELECT name, country FROM users LIMIT 3");
$row = $stmt->fetchAll(\PDO::FETCH_COLUMN);
print_r($row);

$stmt = $pdo->query("SELECT name, country FROM users LIMIT 3");
$row = $stmt->fetchAll(\PDO::FETCH_COLUMN, 1);
print_r($row);

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

Array
(
    [0] => Chris
    [1] => Jamie
    [2] => Robin
)

Array
(
    [0] => Ukraine
    [1] => England
    [2] => Germany
)

PDO::FETCH_KEY_PAIR (int)

В режиме PDO::FETCH_KEY_PAIR возвращается массив пар «ключ — значение», в котором ключи соответствуют первому столбцу. В этом режиме в запросе указывают только 2 столбца. Режим выборки вернёт осмысленные результаты только при вызове метода PDOStatement::fetchAll().

Замечание: Значения потеряются, если первый столбец содержит неуникальные значения. Невозможно определить, какое значение или какие значения теряются.

<?php

$stmt = $pdo->query("SELECT name, country FROM users LIMIT 3");
$row = $stmt->fetchAll(\PDO::FETCH_KEY_PAIR);
print_r($row);

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

Array
(
    [Chris] => Ukraine
    [Jamie] => England
    [Robin] => Germany
)

PDO::FETCH_FUNC (int)

В этом режиме возвращается значение, которое вернёт функция обратного вызова. Режим работает только с методом PDOStatement::fetchAll().

Значения столбцов становятся аргументами функции. По значениям аргументов невозможно получить названия столбцов. При определении пользовательской функции проверяют соответствие порядка столбцов в запросе порядку параметров функции.

Замечание: Режим PDO::FETCH_GROUP группирует, а режим PDO::FETCH_UNIQUE уникализирует результаты выборки до вызова пользовательской функции обратного вызова.

<?php

function valueCreator($col1, $col2, $col3)
{
    return [
        'col1' => $col1,
        'col2' => strtoupper($col2),
        'col3' => $col3,
        'customKey' => 'customValue',
    ];
}

$stmt = $pdo->query("SELECT userid, name, country FROM users LIMIT 3");
$row = $stmt->fetchAll(\PDO::FETCH_FUNC, valueCreator(...));
print_r($row);

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

Array
(
    [0] => Array
        (
            [col1] => 104
            [col2] => SAM
            [col3] => Ukraine
            [customKey] => customValue
        )

    [1] => Array
        (
            [col1] => 105
            [col2] => JAMIE
            [col3] => England
            [customKey] => customValue
        )

    [2] => Array
        (
            [col1] => 107
            [col2] => ROBIN
            [col3] => Germany
            [customKey] => customValue
        )

)

PDO::FETCH_OBJ (int)

В режиме PDO::FETCH_OBJ возвращается объект stdClass.

См. также описания метода PDOStatement::fetchObject() и режима PDO::FETCH_CLASS.

<?php

$stmt = $pdo->query("SELECT userid, name, country FROM users");
$row = $stmt->fetch(\PDO::FETCH_OBJ);
print_r($row);

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

stdClass Object
(
    [userid] => 104
    [name] => Chris
    [country] => Ukraine
)

PDO::FETCH_CLASS (int)

В этом режиме возвращается объект заданного класса. Дополнительную информацию о поведении даёт описание флагов опций.

Свойство объявится динамически, если класс не содержит свойства с названием возвращаемого столбца. Объявление динамических свойств устарело и начиная с PHP 9.0 вызовет ошибку.

См. также описание метода PDOStatement::fetchObject().

<?php

class TestEntity
{
    public $userid;

    public $name;

    public $country;

    public $referred_by_userid;

    public function __construct()
    {
        print "Конструктор вызвали со следующим количеством аргументов: " . count(func_get_args()) . "\n";
        print "Свойства устанавливаются до вызова конструктора? "
            . (isset($this->name) ? 'Да' : 'Нет') . "\n";
    }
}

$stmt = $db->query(
    "SELECT userid, name, country, referred_by_userid FROM users"
);

$stmt->setFetchMode(PDO::FETCH_CLASS, TestEntity::class);

$result = $stmt->fetch();

var_dump($result);

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

Конструктор вызвали со следующим количеством аргументов: 0
Свойства устанавливаются до вызова конструктора? Да
object(TestEntity)#3 (4) {
  ["userid"]=>
  int(104)
  ["name"]=>
  string(5) "Chris"
  ["country"]=>
  string(7) "Ukraine"
  ["referred_by_userid"]=>
  NULL
}

PDO::FETCH_CLASSTYPE (int)

Опция работает только в сочетании с режимом PDO::FETCH_CLASS и другими опциями режима.

С этой опцией модуль PDO возвращает данные в объекте класса, название которого совпадает с названием первого столбца в запросе.

Модуль вернет объект stdClass, без выдачи предупреждения или ошибки, если заданный класс недоступен.

<?php

class TestEntity
{
    public $userid;

    public $name;

    public $country;

    public $referred_by_userid;

    public function __construct()
    {
        print "Конструктор вызвали со следующим количеством аргументов: " . count(func_get_args()) . "\n";
        print "Свойства устанавливаются до вызова конструктора? "
            . (isset($this->name) ? 'Да' : 'Нет') . "\n";
    }
}

$stmt = $db->query(
    "SELECT 'TestEntity', userid, name, country, referred_by_userid FROM users"
);

$stmt->setFetchMode(PDO::FETCH_CLASS | PDO::FETCH_CLASSTYPE);

$result = $stmt->fetch();

var_dump($result);

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

Конструктор вызвали со следующим количеством аргументов: 0
Свойства устанавливаются до вызова конструктора? Да
object(TestEntity)#3 (4) {
  ["userid"]=>
  int(104)
  ["name"]=>
  string(5) "Chris"
  ["country"]=>
  string(7) "Ukraine"
  ["referred_by_userid"]=>
  NULL
}

PDO::FETCH_PROPS_LATE (int)

Опция работает только в сочетании с режимом PDO::FETCH_CLASS и другими опциями режима.

С этой опцией конструктор вызывается до установки свойств.

<?php

class TestEntity
{
    public $userid;

    public $name;

    public $country;

    public $referred_by_userid;

    public function __construct()
    {
        print "Конструктор вызвали со следующим количеством аргументов: " . count(func_get_args()) . "\n";
        print "Свойства устанавливаются до вызова конструктора? "
            . (isset($this->name) ? 'Да' : 'Нет') . "\n";
    }
}

$stmt = $db->query(
    "SELECT userid, name, country, referred_by_userid FROM users"
);

$stmt->setFetchMode(PDO::FETCH_CLASS | PDO::FETCH_PROPS_LATE, TestEntity::class);

$result = $stmt->fetch();
var_dump($result);

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

Конструктор вызвали со следующим количеством аргументов: 0
Свойства устанавливаются до вызова конструктора? Нет
object(TestEntity)#3 (4) {
  ["userid"]=>
  int(104)
  ["name"]=>
  string(5) "Chris"
  ["country"]=>
  string(7) "Ukraine"
  ["referred_by_userid"]=>
  NULL
}

PDO::FETCH_SERIALIZE (int)

Внимание

Начиная с PHP 8.1.0 функциональность УСТАРЕЛА. Полагаться на функциональность настоятельно не рекомендуют.

Режим выборки работает только в сочетании с режимом PDO::FETCH_CLASS и опциями режима.

Режим устанавливают только с классами, которые реализуют интерфейс Serializable.

Предостережение

Режим не поддерживает сами строки с результатом сериализации объекта, как это делает функция serialize().

Предостережение

Режим выборки не вызывает конструктор.

<?php

class TestEntity implements Serializable
{
    public $userid;

    public $name;

    public $country;

    public $referred_by_userid;

    public function __construct()
    {
        print "Конструктор вызвали со следующим количеством аргументов: " . count(func_get_args()) . "\n";
        print "Свойства устанавливаются до вызова конструктора? "
            . (isset($this->name) ? 'Да' : 'Нет') . "\n";
    }

    public function serialize()
    {
        return join(
            "|",
            [$this->userid, $this->name, $this->country, $this->referred_by_userid]
        );
    }

    public function unserialize(string $data)
    {
        $parts = explode("|", $data);
        $this->userid = (int) $parts[0];
        $this->name = $parts[1];
        $this->country = $parts[2];

        $refId = $parts[3];
        $this->referred_by_userid = ($refId === "" ? null : (int) $refId);
    }
}

print "Настройка записи (конструктор вызывается вручную):\n";
$db->exec(
    "CREATE TABLE serialize (
        sdata TEXT
    )"
);

$origObj = new TestEntity();
$origObj->userid = 200;
$origObj->name = 'Seri';
$origObj->country = 'Syria';
$origObj->referred_by_userid = null;

$insert = $db->prepare("INSERT INTO serialize (sdata) VALUES (:sdata)");
$insert->execute(['sdata' => $origObj->serialize()]);

print "\nПолучаем результат:\n";

$query = "SELECT sdata FROM serialize";

$stmt = $db->query($query);

// ПРИМЕЧАНИЕ: Конструктор не вызывается!
$stmt->setFetchMode(PDO::FETCH_CLASS | PDO::FETCH_SERIALIZE, TestEntity::class);

$result = $stmt->fetch();

var_dump($result);

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

Deprecated: TestEntity implements the Serializable interface, which is deprecated. Implement __serialize() and __unserialize() instead (or in addition, if support for old PHP versions is necessary) in Standard input code on line 2
Настройка записи (конструктор вызывается вручную):
Конструктор вызвали со следующим количеством аргументов: 0
Свойства устанавливаются до вызова конструктора? Нет

Получаем результат:
Deprecated: PDOStatement::setFetchMode(): The PDO::FETCH_SERIALIZE mode is deprecated in Standard input code on line 58

Deprecated: PDOStatement::fetch(): The PDO::FETCH_SERIALIZE mode is deprecated in Standard input code on line 59
object(TestEntity)#5 (4) {
  ["userid"]=>
  int(200)
  ["name"]=>
  string(4) "Seri"
  ["country"]=>
  string(5) "Syria"
  ["referred_by_userid"]=>
  NULL
}

PDO::FETCH_BOUND (int)

Опция несовместима с методом PDOStatement::fetchAll().

С этой опцией модуль не возвращает результат напрямую, а привязывает значения к переменным, которые указали методом PDOStatement::bindColumn(). Вызов метода выборки возвращает значение true.

Замечание:
Для корректной работы подготовленных SQL-инструкций переменные привязывают после выполнения запроса.

<?php

$query = "SELECT users.userid, users.name, users.country, referrer.name
    FROM users
    LEFT JOIN users AS referrer ON users.referred_by_userid = referrer.userid";
$stmt = $db->prepare($query);
$stmt->execute();

$stmt->bindColumn('userid', $userId);
$stmt->bindColumn('name', $name);
$stmt->bindColumn('country', $country);
// Связываем переменную по позиции столбца, чтобы разрешить дублирование названия столбца.
// А лучше вместо названия столбца указать в SQL-запросе псевдоним,
// чтобы не сломать привязку при изменении запроса,
// например: referrer.name AS referrer_name
$stmt->bindColumn(4, $referrerName);

while ($stmt->fetch(\PDO::FETCH_BOUND)) {
    print join("\t", [$userId, $name, $country, ($referrerName ?? 'NULL')]) . "\n";
}

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

104	Chris	Ukraine	NULL
105	Jamie	England	NULL
107	Robin	Germany	Chris
108	Sean	Ukraine	NULL
109	Toni	Germany	NULL
110	Toni	Germany	NULL

PDO::FETCH_INTO (int)

Режим выборки несовместим с методом PDOStatement::fetchAll().

Режим выборки обновляет свойства заданного объекта. Метод выборки возвращает объект, если выполнился успешно.

В этом режиме обновляются только свойства с модификатором public, а защищённые и закрытые свойства игнорируются, попытка обновить свойство с модификатором readonly вызовет фатальную ошибку.

Предостережение

Невозможно изменить обновляемый объект без вызова метода PDOStatement::setFetchMode() между извлечением каждой записи.

<?php

class TestEntity
{
    public $userid;

    public $name;

    public $country;

    public $referred_by_userid;
}

$obj = new TestEntity();
$stmt->setFetchMode(\PDO::FETCH_INTO, $obj);

$stmt = $db->query("SELECT userid, name, country, referred_by_userid FROM users");
$result = $stmt->fetch();
var_dump($result);

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

object(TestEntity)#3 (4) {
  ["userid"]=>
  int(104)
  ["name"]=>
  string(5) "Chris"
  ["country"]=>
  string(7) "Ukraine"
  ["referred_by_userid"]=>
  NULL
}

PDO::FETCH_LAZY (int)

Режим выборки несовместим с методом PDOStatement::fetchAll().

Режим возвращает объект PDORow, который поддерживает доступ к свойствам как через синтаксис доступа к элементам массива, так и через синтаксис доступа к свойствам объекта, сочетая поведение режимов PDO::FETCH_BOTH и PDO::FETCH_OBJ. В этом режиме при извлечении очередной строки метод подготавливает объект с результатами «ленивым» способом — не создаёт новый экземпляр, а обновляет значения свойств в том же объекте.

Ленивое извлечение повышает эффективность доступа к небуферизованным результатам на сервере баз данных, с точки зрения работы с памятью на стороне PHP. Буферизует ли модуль PDO результаты на клиентской стороне, зависит от специфичного для базы данных драйвера и его конфигурации.

Предостережение

При доступе к неопределённым свойствам или ключам объект PDORow вернет значение NULL, без ошибки или предупреждения. Это затруднит обнаружение и отладку ошибок, которые возникают из-за опечаток, или запросов, которые не возвращают ожидаемые данные.

Предостережение

Возвращаемый объект PDORow обновляется каждый раз при извлечении результата.

<?php

$stmt = $db->query("SELECT userid, name, country, referred_by_userid FROM users");
$result = $stmt->fetch(\PDO::FETCH_LAZY);

print "ID: " . $result[0] . "\n";
print "Name: {$result->name}\n";
print "Country: " . $result['country'] . "\n";
// Возвращается NULL. Без выдачи предупреждения или ошибки.
print "Неопределённое свойство: " . var_export($result->does_not_exist, true) . "\n";

$differentResult = $stmt->fetch(\PDO::FETCH_LAZY);
// Предыдущий объект PDORow теперь указывает на вновь извлечённый результат
print "ID: " . $result[0] . "\n";

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

ID: 104
Name: Chris
Country: Ukraine
Неопределённое свойство: NULL
ID: 105

PDO::FETCH_GROUP (int)

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

При объединении с режимом PDO::FETCH_UNIQUE оба проиндексируют результаты выборки по одному и тому же столбцу, поэтому сочетание режимов бесполезно.

Режим выборки с группировкой по первому столбцу комбинируют со следующими режимами: PDO::FETCH_ASSOC, PDO::FETCH_BOTH, PDO::FETCH_NAMED, PDO::FETCH_NUM, PDO::FETCH_COLUMN или PDO::FETCH_FUNC.

Объект PDOStatement обработает результаты в режиме выборки по умолчанию, если для режима группировки не задали режим из приведённого списка.

<?php

$stmt = $pdo->query("SELECT country, userid, name FROM users");
$row = $stmt->fetchAll(\PDO::FETCH_GROUP | \PDO::FETCH_ASSOC);
print_r($row);

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

Array
(
    [Ukraine] => Array
        (
            [0] => Array
                (
                    [userid] => 104
                    [name] => Chris
                )

            [1] => Array
                (
                    [userid] => 108
                    [name] => Sean
                )

        )
    [England] => Array
        (
            [0] => Array
                (
                    [userid] => 105
                    [name] => Jamie
                )

        )

    [Germany] => Array
        (
            [0] => Array
                (
                    [userid] => 107
                    [name] => Robin
                )

            [1] => Array
                (
                    [userid] => 109
                    [name] => Toni
                )
        )
)

В приведённом примере массивы со значениями построчных результатов не включают первый столбец, который доступен только как ключ. Для включения в состав массива название столбца повторяют в запросе, как в следующем примере:

<?php

$stmt = $pdo->query("SELECT country, userid, name, country FROM users");
$row = $stmt->fetchAll(\PDO::FETCH_GROUP | \PDO::FETCH_ASSOC);
print_r($row);

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

Array
(
    [Ukraine] => Array
        (
            [0] => Array
                (
                    [userid] => 104
                    [name] => Chris
                    [country] => Ukraine
                )

            [1] => Array
                (
                    [userid] => 108
                    [name] => Sean
                    [country] => Ukraine
                )

        )
    [England] => Array
        (
            [0] => Array
                (
                    [userid] => 105
                    [name] => Jamie
                    [country] => England
                )

        )

    [Germany] => Array
        (
            [0] => Array
                (
                    [userid] => 107
                    [name] => Robin
                    [country] => Germany
                )

            [1] => Array
                (
                    [userid] => 109
                    [name] => Toni
                    [country] => Germany
                )
        )
)

PDO::FETCH_UNIQUE (int)

В режиме PDO::FETCH_UNIQUE возвращается массив, в котором записи индексируются по первому столбцу, и возвращается только одна запись для значения индекса. Режим выборки работает только с методом PDOStatement::fetchAll().

При объединении с режимом PDO::FETCH_GROUP оба проиндексируют результаты выборки по одному и тому же столбцу, поэтому сочетание режимов бесполезно.

Режим выборки с уникализацией по первому столбцу комбинируют со следующими режимами: PDO::FETCH_ASSOC, PDO::FETCH_BOTH, PDO::FETCH_NAMED, PDO::FETCH_NUM, PDO::FETCH_COLUMN или PDO::FETCH_FUNC.

Объект PDOStatement обработает результаты в режиме выборки по умолчанию, если для режима уникализации не задали режим из приведённого списка.

При работе с уникальным столбцом наподобие ID режим быстро возвращает результаты, поскольку БД содержит индекс для такого значения.

Замечание: При выборке из неуникальных столбцов значения потеряются. Невозможно определить, какое значение или какие значения теряются.

Предостережение

Фильтрацию записей лучше выполнять в SQL-запросе, когда возможно. База данных построит план запроса с учётом индексов, чтобы оптимизировать фильтрацию и вернуть только искомые записи. Выборка из базы данных избыточного количества записей значительно увеличивает потребление памяти и время выполнения запроса для более крупных наборов данных с результатами запроса.

<?php

$stmt = $pdo->query("SELECT userid, name, country FROM users LIMIT 3");
$row = $stmt->fetchAll(\PDO::FETCH_UNIQUE | \PDO::FETCH_ASSOC);
print_r($row);

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

Array
(
    [104] => Array
        (
            [name] => Chris
            [country] => Ukraine
        )

    [105] => Array
        (
            [name] => Jamie
            [country] => England
        )

    [107] => Array
        (
            [name] => Robin
            [country] => Germany
        )

)

<?php

$stmt = $pdo->query("SELECT userid, userid, name, country FROM users LIMIT 3");
$row = $stmt->fetchAll(\PDO::FETCH_UNIQUE | \PDO::FETCH_ASSOC);
print_r($row);

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

Array
(
    [104] => Array
        (
            [userid] => 104
            [name] => Chris
            [country] => Ukraine
        )

    [105] => Array
        (
            [userid] => 105
            [name] => Jamie
            [country] => England
        )

    [107] => Array
        (
            [userid] => 107
            [name] => Robin
            [country] => Germany
        )

)