fetch_object

mysqli_fetch_object() lê a próxima linha de um conjunto de resultados MySQLi e a retorna como um object PHP cujas propriedades são nomeadas de acordo com as colunas da sua consulta. É o primo orientado a objetos de mysqli_fetch_assoc() e mysqli_fetch_array(): em vez de escrever $row['name'], você escreve $row->name.

Este capítulo aborda a assinatura da função, como acessar colunas, como hidratar linhas em suas próprias classes, tratamento de erros e quando usá-la em vez dos fetchers baseados em array.

Sintaxe

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

No estilo orientado a objetos, a mesma chamada é $result->fetch_object().

Valor de retorno:

• Um object preenchido com as colunas da linha quando uma linha está disponível.
• null quando não há mais linhas (é isso que encerra o laço while).
• false em caso de falha.

Uso básico

Chame a função em um laço while. Cada iteração avança o ponteiro interno de linha em um até que null seja retornado:

<?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);
?>

Cada $row é um object stdClass, portanto suas propriedades correspondem aos nomes das colunas selecionadas (ou seus aliases). Se uma coluna não existir na linha, você receberá um aviso e null, portanto sempre selecione as colunas que pretende ler.

Importante — nomes de colunas, não posições. Como o object é indexado por nome, SELECT * e SELECT name, email se comportam de forma diferente em relação à ordem. Prefira nomear colunas explicitamente para que uma mudança de esquema não quebre o acesso às propriedades.

Hidratando linhas em sua própria classe

A verdadeira força de mysqli_fetch_object() em relação aos fetchers de array é que ela pode construir instâncias de sua classe. Passe o nome da classe como segundo argumento:

<?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
}
?>

A atribuição de propriedades ocorre antes de o construtor ser executado. O PHP define os valores das colunas diretamente nas propriedades do objeto primeiro e, em seguida, chama __construct(). Se sua classe precisar que o construtor veja esses valores, leve essa ordem em consideração:

<?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"]);
?>

Tratamento de ausência de linhas e erros

Diferencie "sem mais linhas" (null) de uma falha genuína (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;
    }
}
?>

Para código em produção, ative o modo de exceção para que consultas com falha lancem exceções em vez de retornar false:

<?php
mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);

fetch_object vs. os outros fetchers

Escolha mysqli_fetch_object() quando quiser acesso limpo via ->propriedade ou quando quiser que cada linha seja convertida em um objeto de domínio com comportamento (métodos). Escolha os fetchers de array quando precisar apenas de dados simples para iterar ou serializar.

Boas práticas

• Use prepared statements para qualquer valor proveniente de entrada do usuário, a fim de prevenir injeção SQL; você ainda pode chamar fetch_object() no resultado de um prepared statement.
• Libere o resultado com mysqli_free_result() quando terminar, para liberar memória em conjuntos de resultados grandes.
• Selecione apenas as colunas necessárias para que as propriedades do object sejam previsíveis e as consultas permaneçam rápidas.

Conclusão

mysqli_fetch_object() percorre um conjunto de resultados MySQLi uma linha por vez, retornando cada linha como um object com propriedades nomeadas pelas colunas — ou, quando fornecido um nome de classe, como uma instância completamente construída da sua própria classe. Retorna null quando as linhas se esgotam e false em caso de falha. Use-a quando a sintaxe de object ou a hidratação de domínio for mais legível do que os fetchers baseados em array, como mysqli_fetch_assoc().

Prática