fetch_assoc

A função mysqli_fetch_assoc() busca uma linha de um conjunto de resultados MySQLi e a retorna como um array associativo, onde cada chave é o nome de uma coluna da sua consulta. Esta página explica sua sintaxe, valor de retorno, como ela se comporta dentro de um laço, os erros mais comuns e como ela difere de outras funções de busca relacionadas.

O que a mysqli_fetch_assoc() faz

Quando você executa uma consulta SELECT, o MySQLi retorna um conjunto de resultados — um ponteiro para as linhas correspondidas pelo banco de dados. A mysqli_fetch_assoc() retira a próxima linha desse conjunto e entrega a você como um array indexado pelo nome da coluna:

$row = mysqli_fetch_assoc($result);
echo $row['email']; // access a value by its column name

Cada chamada avança um cursor interno, então chamar a função repetidamente percorre as linhas uma a uma. Quando não há mais linhas, ela retorna null.

Sintaxe

mysqli_fetch_assoc(mysqli_result $result): array|null|false

Se duas colunas no seu SELECT tiverem o mesmo nome (por exemplo, um JOIN retornando duas colunas id), apenas a última sobreviverá no array — use aliases de coluna (SELECT a.id AS user_id) para manter ambas.

Buscando linhas em um laço

Quase sempre você chama mysqli_fetch_assoc() dentro de um laço while. Como ela retorna null (falso) após a última linha, o laço termina automaticamente:

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

if (mysqli_connect_errno()) {
    die("Connection failed: " . mysqli_connect_error());
}

$result = mysqli_query($mysqli, "SELECT id, name, price FROM products");

if ($result) {
    while ($row = mysqli_fetch_assoc($result)) {
        echo $row['id'] . ": " . $row['name'] . " ($" . $row['price'] . ")\n";
    }
    mysqli_free_result($result);
} else {
    echo "Query failed: " . mysqli_error($mysqli);
}

mysqli_close($mysqli);
?>

Verificamos a conexão com mysqli_connect_errno(), executamos a consulta e então iniciamos o laço. Cada iteração atribui a próxima linha a $row; quando o conjunto se esgota, a atribuição retorna null, a condição do while se torna falsa e o laço para. mysqli_free_result() libera a memória ocupada pelo conjunto de resultados após terminarmos.

Vendo o array que ela retorna

Você não precisa de um banco de dados para entender o formato de uma linha. O trecho abaixo constrói um array idêntico ao que uma única chamada de mysqli_fetch_assoc() retornaria e o imprime, para que você possa ver as chaves com os nomes das colunas:

<?php
// This is the structure mysqli_fetch_assoc() hands back for one row.
$row = [
    "id"    => 1,
    "name"  => "Keyboard",
    "price" => 29.99,
];

echo "Product: " . $row["name"] . "\n";
echo "Price:   $" . $row["price"] . "\n";

print_r($row);
?>

Ao executar, imprime:

Product: Keyboard
Price:   $29.99
Array
(
    [id] => 1
    [name] => Keyboard
    [price] => 29.99
)

Erros comuns

• Chamá-la em uma consulta que falhou. mysqli_query() retorna false em caso de erro, e passar false para mysqli_fetch_assoc() é inválido. Sempre verifique $result primeiro, como no laço acima.
• Esquecer que ela retorna apenas uma linha. Uma única chamada retorna a próxima linha, não a tabela inteira. Use um laço para ler todas.
• Usar == em vez de atribuição. O laço usa $row = mysqli_fetch_assoc($result) (atribuição). Usar == nunca avançaria o cursor e poderia causar um laço infinito.
• Tratá-la como acesso numérico. Use $row['name'], não $row[0]. Para chaves numéricas, use mysqli_fetch_row(); para ambas, use mysqli_fetch_array().

Como ela se compara a outras funções de busca

Use mysqli_fetch_assoc() quando quiser código legível e autodocumentado que refere-se às colunas pelo nome e você está processando as linhas uma a uma.

Conclusão

mysqli_fetch_assoc() é a função ideal para ler um conjunto de resultados MySQLi como arrays associativos indexados pelo nome da coluna. Combine-a com um laço while e uma rápida verificação de que a consulta foi bem-sucedida, e você poderá iterar conjuntos de resultados com segurança. Para mais informações, veja PHP MySQLi, arrays associativos e o laço while.

Prática