fetch_field

A função mysqli_fetch_field() retorna metadados sobre uma coluna — não os dados contidos nela. A cada chamada, você obtém um object descrevendo a próxima coluna do conjunto de resultados: seu nome, tipo de dado, comprimento, a tabela de origem e diversos sinalizadores. Esta página explica quando isso é útil, como a função se comporta, o que significa cada propriedade e como utilizá-la nos estilos orientado a objetos e procedural.

O que o mysqli_fetch_field() faz

mysqli_fetch_field() percorre as colunas de um conjunto de resultados uma por vez, como um cursor. O conjunto de resultados mantém um ponteiro de campo interno; cada chamada bem-sucedida avança esse ponteiro em uma posição. Ao chegar à última coluna, a chamada seguinte retorna false, o que torna conveniente o uso em um laço while.

Ela retorna metadados, portanto você não precisa de linhas reais para utilizá-la — uma consulta que não retorna nenhuma linha ainda assim descreve suas colunas. É exatamente por isso que ela é útil: você pode inspecionar a estrutura de um resultado antes de processá-lo.

Sintaxe (ambos os estilos são equivalentes):

// Object-oriented style
$fieldInfo = $result->fetch_field();

// Procedural style
$fieldInfo = mysqli_fetch_field($result);

Ela recebe o conjunto de resultados como único argumento e retorna um object em caso de sucesso ou false quando não há mais campos.

Lendo metadados de coluna

O exemplo abaixo conecta ao banco de dados, executa um SELECT e percorre as colunas do resultado. Cada iteração imprime o nome, o código de tipo e o comprimento máximo da coluna.

Como usar a função mysqli_fetch_field()?

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

if ($mysqli->connect_error) {
    die("Connection failed: " . $mysqli->connect_error);
}

$query = "SELECT * FROM my_table";
$result = $mysqli->query($query);

if ($result) {
    while ($field = $result->fetch_field()) {
        printf("Name: %s\n", $field->name);
        printf("Type: %s\n", $field->type);
        printf("Length: %d\n", $field->length);
    }
} else {
    echo "Query failed: " . $mysqli->error;
}

$result->free();
$mysqli->close();
?>

O laço while ($field = $result->fetch_field()) encerra naturalmente quando fetch_field() retorna false após a última coluna. Como o ponteiro de campo avança a cada chamada, a primeira iteração descreve a primeira coluna, a segunda iteração descreve a segunda coluna, e assim por diante.

O object de campo e suas propriedades

Cada chamada retorna um object semelhante a stdClass. As propriedades mais utilizadas são:

A propriedade type é um inteiro, não uma string legível. O PHP disponibiliza constantes como MYSQLI_TYPE_VARCHAR, MYSQLI_TYPE_LONG (uma coluna inteira) e MYSQLI_TYPE_DATETIME para que você possa comparar:

if ($field->type === MYSQLI_TYPE_LONG) {
    echo "{$field->name} is an integer column\n";
}

Acessando uma coluna específica

fetch_field() é sequencial; portanto, para inspecionar apenas a terceira coluna, por exemplo, você precisaria percorrer o laço até chegar nela ou reposicionar o ponteiro antes. O ponteiro de campo pode ser reposicionado com field_seek(), e uma única coluna pode ser obtida diretamente pelo índice com fetch_field_direct():

// Jump to column index 2 (the third column), then read it
$result->field_seek(2);
$field = $result->fetch_field();
echo $field->name;

Quando usar (e as alternativas)

Use fetch_field() quando quiser iterar sobre colunas e reagir a cada uma — por exemplo, para gerar automaticamente um cabeçalho de tabela, construir um formulário ou decidir como formatar cada valor de acordo com seu tipo.

• Se você precisar dos metadados de todas as colunas de uma só vez, fetch_fields() as retorna como um array em uma única chamada, geralmente mais prático do que um laço.
• Se você precisar apenas de quantas colunas existem, use field_count.
• Para ler os dados reais das linhas em vez dos metadados das colunas, use fetch_assoc() ou fetch_array().

Conclusão

mysqli_fetch_field() oferece uma visão coluna por coluna da estrutura de um conjunto de resultados: nomes, tipos, comprimentos e sinalizadores, avançando pelas colunas a cada chamada. Use-a em um laço para inspecionar uma consulta antes de processar suas linhas, combine-a com field_seek() para acessar uma coluna específica, ou prefira fetch_fields() quando quiser todos os metadados de uma só vez.

Prática