field_seek

Este artículo explica la función mysqli_field_seek() en PHP, que posiciona el cursor de campo en un desplazamiento de campo específico dentro de un conjunto de resultados MySQLi. Explicaremos qué es el cursor de campo, cuándo conviene usar esta función, documentaremos sus parámetros y valor de retorno, y veremos ejemplos prácticos.

¿Qué es el cursor de campo?

Cuando ejecutas una consulta SELECT con mysqli_query(), MySQLi devuelve un conjunto de resultados que contiene metadatos sobre cada columna (su nombre, tabla, tipo, longitud y atributos). Esos metadatos se leen columna por columna mediante mysqli_fetch_field(), y un puntero interno — el cursor de campo — registra qué columna se leerá a continuación.

mysqli_field_seek() permite mover ese puntero a cualquier desplazamiento de columna, de modo que la siguiente llamada a mysqli_fetch_field() devuelva los metadatos de la columna elegida en lugar de la siguiente en la secuencia.

Hay dos conceptos fáciles de confundir, así que conviene mantenerlos separados:

• El cursor de campo controla qué metadatos de columna se leen — se mueve con mysqli_field_seek().
• El cursor de fila controla qué fila de datos se lee — se mueve con mysqli_data_seek().

Esta función solo afecta al cursor de campo; nunca cambia qué filas de datos se devuelven.

Sintaxis

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

En estilo orientado a objetos, el método equivalente es $result->field_seek($index).

Parámetros

• result — Un object mysqli_result devuelto por mysqli_query(), mysqli_store_result() o mysqli_use_result().
• index — El desplazamiento de campo (basado en cero) al que se desea ir. Debe estar entre 0 y el número de campos menos uno (véase mysqli_field_count()). Un desplazamiento inválido genera una advertencia.

Valor de retorno

Devuelve true. (Históricamente la forma procedimental documentaba un boolean; desde PHP 8.0 siempre devuelve true y lanza un ValueError si el desplazamiento está fuera de rango.)

Uso básico

Llama a la función sobre un conjunto de resultados válido y luego obtén los metadatos del campo deseado:

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

Aquí la consulta selecciona tres columnas. Los desplazamientos son de base cero, por lo que el desplazamiento 0 corresponde a id, 1 a name y 2 a email. Al posicionarse en 2, la siguiente llamada a mysqli_fetch_field() devuelve los metadatos de la columna email.

Volver a leer los metadatos de una sola columna

Un uso práctico consiste en leer los metadatos de la misma columna dos veces sin volver a ejecutar la consulta. Como mysqli_fetch_field() avanza el cursor, se utiliza seek para restablecerlo:

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

¿Cuándo usaría esto?

En el código moderno rara vez se necesita: la mayoría de las aplicaciones obtienen filas como arrays asociativos u objetos con mysqli_fetch_assoc() e ignoran por completo los metadatos de columna. mysqli_field_seek() resulta útil cuando:

• Se construye una herramienta genérica (un exportador CSV, un inspector de esquemas, un renderizador de cuadrícula) que inspecciona columnas por posición.
• Se necesita leer repetidamente los metadatos de una columna específica sin obtener todos los campos con mysqli_fetch_fields().
• Se mantiene código heredado que recorre los metadatos del conjunto de resultados columna por columna.

Conclusión

mysqli_field_seek() reposiciona el cursor de campo dentro de un conjunto de resultados MySQLi para que la siguiente llamada a mysqli_fetch_field() devuelva la columna elegida. Solo actúa sobre los metadatos de columna — para saltar entre filas de datos, usa mysqli_data_seek(). Aunque es poco frecuente en el código de aplicaciones cotidianas, resulta muy útil para herramientas basadas en metadatos y para comprender flujos de trabajo heredados con MySQLi.

Práctica