fetch_object

mysqli_fetch_object() читает следующую строку результирующего набора MySQLi и возвращает её как PHP object, свойства которого названы по именам столбцов запроса. Это объектно-ориентированный аналог mysqli_fetch_assoc() и mysqli_fetch_array(): вместо $row['name'] используется запись $row->name.

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

Синтаксис

mysqli_fetch_object(
    mysqli_result $result,
    string $class = "stdClass",
    array $constructor_args = []
): object|null|false

В объектно-ориентированном стиле тот же вызов выглядит как $result->fetch_object().

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

• Object, заполненный столбцами строки, если строка доступна.
• null, когда строк больше нет (именно это завершает цикл while).
• false при ошибке.

Базовое использование

Вызывайте функцию в цикле while. На каждой итерации внутренний указатель строки сдвигается на одну позицию, пока не будет возвращён null:

<?php
$mysqli = mysqli_connect("localhost", "username", "password", "database");

$result = mysqli_query($mysqli, "SELECT name, email FROM users");

if ($result) {
    while ($row = mysqli_fetch_object($result)) {
        printf("%s (%s)\n", $row->name, $row->email);
    }
    mysqli_free_result($result);
}

mysqli_close($mysqli);
?>

Каждый $row является object типа stdClass, поэтому его свойства соответствуют именам выбранных столбцов (или их псевдонимам). Если столбец отсутствует в строке, вы получите предупреждение и null, поэтому всегда выбирайте только те столбцы, которые собираетесь читать.

Важно — имена столбцов, а не позиции. Поскольку object индексируется по имени, SELECT * и SELECT name, email ведут себя по-разному с точки зрения порядка. Предпочтительно явно указывать имена столбцов, чтобы изменение схемы не нарушило доступ к свойствам.

Гидратация строк в собственный класс

Главное преимущество mysqli_fetch_object() перед массивными методами выборки состоит в том, что он может создавать экземпляры вашего класса. Передайте имя класса вторым аргументом:

<?php
class User
{
    public string $name;
    public string $email;

    public function greet(): string
    {
        return "Hi, I'm {$this->name}";
    }
}

$result = mysqli_query($mysqli, "SELECT name, email FROM users");

while ($user = mysqli_fetch_object($result, User::class)) {
    echo $user->greet(), "\n"; // calls a real method on a real User object
}
?>

Присвоение свойств происходит до вызова конструктора. PHP сначала устанавливает значения столбцов непосредственно в свойства object, и лишь затем вызывает __construct(). Если вашему классу нужно, чтобы конструктор видел эти значения, учитывайте данный порядок:

<?php
class Product
{
    public string $name;
    public float  $price;
    public string $label;

    public function __construct(string $currency = "USD")
    {
        // $this->name and $this->price are already set here
        $this->label = "{$this->name}: {$this->price} {$currency}";
    }
}

// Constructor args are passed as the third parameter:
$product = mysqli_fetch_object($result, Product::class, ["EUR"]);
?>

Обработка отсутствия строк и ошибок

Различайте ситуацию «строк больше нет» (null) от реальной ошибки (false):

<?php
$result = mysqli_query($mysqli, "SELECT name FROM users WHERE id = 999");

if ($result === false) {
    echo "Query failed: " . mysqli_error($mysqli);
} else {
    $row = mysqli_fetch_object($result);

    if ($row === null) {
        echo "No user found.";
    } else {
        echo $row->name;
    }
}
?>

В рабочем коде включайте режим исключений, чтобы неудачные запросы генерировали исключения вместо возврата false:

<?php
mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);

fetch_object в сравнении с другими методами выборки

Выбирайте mysqli_fetch_object(), когда вам нужен удобный синтаксис ->property или когда вы хотите превратить каждую строку в доменный object с поведением (методами). Выбирайте массивные методы, когда нужны просто данные для перебора или сериализации.

Рекомендации

• Используйте подготовленные запросы для любых данных, поступающих от пользователя, чтобы предотвратить SQL-инъекции; fetch_object() по-прежнему можно вызывать на результате подготовленного запроса.
• Освобождайте результат с помощью mysqli_free_result() по окончании работы, чтобы освободить память при больших результирующих наборах.
• Выбирайте только нужные столбцы, чтобы свойства object были предсказуемы, а запросы оставались быстрыми.

Заключение

mysqli_fetch_object() обходит результирующий набор MySQLi по одной строке за раз, возвращая каждую строку как object со свойствами, названными по именам столбцов, — или, если указано имя класса, как полностью сконструированный экземпляр вашего собственного класса. При исчерпании строк возвращается null, при ошибке — false. Используйте его, когда объектный синтаксис или доменная гидратация выглядит чище, чем массивные методы выборки, например mysqli_fetch_assoc().

Практика