fetch_fields

A função mysqli_fetch_fields() retorna um array de objetos que descrevem as colunas (campos) de um conjunto de resultados MySQLi — seus nomes, tipos, comprimentos, tabelas de origem e flags. Ela lê metadados sobre as colunas, não os dados das linhas em si. Esta página explica a sintaxe, o que cada objeto de campo contém, quando você precisaria usá-la e as armadilhas mais comuns.

Sintaxe

mysqli_fetch_fields(mysqli_result $result): array

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

• $result — um conjunto de resultados retornado por mysqli_query(), mysqli_store_result() ou mysqli_use_result().
• Valor de retorno — um array de objetos stdClass, um por coluna, na ordem em que as colunas aparecem no resultado. Cada objeto expõe propriedades como name, orgname, table, orgtable, type, length, max_length, decimals e flags.

O que cada objeto de campo contém

Quando usaria isso?

Use mysqli_fetch_fields() quando precisar trabalhar com o resultado de uma consulta de forma genérica — sem conhecer as colunas com antecedência. Casos típicos:

• Construir um painel de administração/grade de dados que renderiza qualquer consulta SELECT *, usando os nomes das colunas como cabeçalhos de tabela.
• Exportar resultados para CSV com uma linha de cabeçalho.
• Verificar se uma coluna é chave primária ou auto-incremento antes de gerar um formulário de edição.

Se você só precisa dos nomes das colunas, esta é a forma mais direta de obtê-los. Para obter a descrição de um campo por vez, use mysqli_fetch_field(); para contar as colunas, use mysqli_field_count().

Exemplo: listar todas as colunas de um conjunto de resultados

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

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

$fields = mysqli_fetch_fields($result);

foreach ($fields as $field) {
    printf("Name: %s, Type: %d, Length: %d\n",
        $field->name, $field->type, $field->length);
}

mysqli_free_result($result);
mysqli_close($mysqli);
?>

O loop foreach percorre o array de objetos de campo e imprime o nome, o código de tipo e o comprimento definido de cada coluna. Para as três colunas selecionadas, a saída será parecida com:

Name: id, Type: 3, Length: 11
Name: name, Type: 253, Length: 255
Name: price, Type: 246, Length: 10

Os valores numéricos de type vêm das constantes MYSQLI_TYPE_* — por exemplo, 3 é MYSQLI_TYPE_LONG (um INT) e 253 é MYSQLI_TYPE_VAR_STRING (um VARCHAR).

Criando um cabeçalho CSV a partir dos nomes dos campos

Como o array de campos é genérico, você pode criar uma linha de cabeçalho para qualquer consulta sem precisar codificar os nomes das colunas diretamente:

<?php
$result = mysqli_query($mysqli, "SELECT * FROM products");

$header = array_map(
    fn($field) => $field->name,
    mysqli_fetch_fields($result)
);

echo implode(",", $header), "\n"; // id,name,price

array_map() transforma o array de objetos de campo em um array simples de nomes, e implode() os une com vírgulas.

Armadilhas

• mysqli_fetch_fields() é somente para metadados. Ela não move o cursor de linha e não retorna nenhum dado de linha — combine-a com mysqli_fetch_assoc() ou mysqli_fetch_array() para ler as linhas reais.
• max_length é 0 com resultados não bufferizados. É preenchido somente quando o conjunto de resultados completo é bufferizado no cliente via mysqli_store_result() (que mysqli_query() usa por padrão). Com mysqli_use_result(), o valor permanece 0.
• type e flags são inteiros, não strings. Compare-os com as constantes MYSQLI_TYPE_* e MYSQLI_*_FLAG em vez de números mágicos, para que a intenção fique clara.
• Sempre verifique se $result é verdadeiro antes de chamar a função — uma consulta com falha retorna false, e passar false gera um erro.

Funções relacionadas

• mysqli_fetch_field() — obtém os metadados de uma coluna por vez.
• mysqli_field_count() — conta as colunas no resultado.
• mysqli_field_seek() — move o cursor de campo para uma coluna específica.
• mysqli_fetch_assoc() — lê as linhas do resultado como arrays associativos.

Prática