field_seek

Este artigo aborda a função mysqli_field_seek() em PHP, que posiciona o cursor de campo em um deslocamento de campo específico dentro de um conjunto de resultados MySQLi. Explicaremos o que é o cursor de campo, quando você precisaria usar esta função, documentaremos seus parâmetros e valor de retorno, e apresentaremos exemplos funcionais.

O que é o cursor de campo?

Quando você executa uma consulta SELECT com mysqli_query(), o MySQLi retorna um conjunto de resultados que contém metadados sobre cada coluna (seu nome, tabela, tipo, comprimento e flags). Esses metadados são lidos uma coluna por vez usando mysqli_fetch_field(), e um ponteiro interno — o cursor de campo — rastreia qual coluna será lida a seguir.

mysqli_field_seek() permite mover esse ponteiro para qualquer deslocamento de coluna, de modo que a próxima chamada a mysqli_fetch_field() retorne os metadados da coluna escolhida, em vez da próxima na sequência.

Duas coisas são fáceis de confundir, portanto mantenha-as separadas:

• O cursor de campo controla os metadados de qual coluna você lê — movido com mysqli_field_seek().
• O cursor de linha controla qual linha de dados você lê — movido com mysqli_data_seek().

Esta função afeta apenas o cursor de campo; ela nunca altera quais linhas de dados são retornadas.

Sintaxe

mysqli_field_seek(mysqli_result $result, int $index): true

No estilo orientado a objetos, o método equivalente é $result->field_seek($index).

Parâmetros

• result — Um object mysqli_result retornado por mysqli_query(), mysqli_store_result() ou mysqli_use_result().
• index — O deslocamento de campo com base zero para o qual mover. Deve estar entre 0 e o número de campos menos um (consulte mysqli_field_count()). Um deslocamento inválido aciona um aviso.

Valor de retorno

Retorna true. (Historicamente, a forma procedural documentava um boolean; desde o PHP 8.0, sempre retorna true e lança um ValueError para um deslocamento fora do intervalo.)

Uso básico

Chame a função em um conjunto de resultados válido e, em seguida, busque os metadados do campo desejado:

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

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

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

if (!$result) {
    die("Query failed: " . mysqli_error($mysqli));
}

// Skip ahead to the third column (offset 2 = "email").
mysqli_field_seek($result, 2);
$field = mysqli_fetch_field($result);

printf("Field name: %s\n", $field->name); // Field name: email

mysqli_close($mysqli);
?>

Aqui a consulta seleciona três colunas. Os deslocamentos têm base zero, portanto o deslocamento 0 é id, 1 é name e 2 é email. Após mover para 2, o próximo mysqli_fetch_field() retorna os metadados da coluna email.

Relendo os metadados de uma única coluna

Um uso prático é ler os metadados da mesma coluna duas vezes sem executar a consulta novamente. Como mysqli_fetch_field() avança o cursor, você volta ao início para redefini-lo:

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

mysqli_field_seek($result, 1);
$first = mysqli_fetch_field($result);   // reads "name", cursor now at 2

mysqli_field_seek($result, 1);          // rewind to the same column
$again = mysqli_fetch_field($result);   // reads "name" again

printf("%s == %s\n", $first->name, $again->name); // name == name
?>

Quando eu usaria isso?

No código moderno, raramente você precisará disso: a maioria das aplicações busca linhas em arrays associativos ou objects com mysqli_fetch_assoc() e ignora completamente os metadados das colunas. mysqli_field_seek() é útil quando você está:

• Construindo uma ferramenta genérica (um exportador CSV, um inspetor de esquema, um renderizador de grade) que inspeciona colunas por posição.
• Lendo os metadados de uma coluna específica repetidamente sem rebuscar todos os campos com mysqli_fetch_fields().
• Mantendo código legado que percorre metadados de conjuntos de resultados coluna por coluna.

Conclusão

mysqli_field_seek() reposiciona o cursor de campo dentro de um conjunto de resultados MySQLi para que a próxima chamada a mysqli_fetch_field() retorne a coluna escolhida. Funciona apenas com metadados de colunas — para navegar entre linhas de dados, use mysqli_data_seek(). Embora seja incomum no código de aplicações do dia a dia, é bastante útil para ferramentas orientadas a metadados e para compreender fluxos de trabalho legados com MySQLi.

Prática