field_seek

Эта статья посвящена функции mysqli_field_seek() в PHP, которая устанавливает курсор поля на заданное смещение в результирующем наборе MySQLi. Мы объясним, что такое курсор поля, когда стоит использовать эту функцию, опишем её параметры и возвращаемое значение, а также рассмотрим рабочие примеры.

Что такое курсор поля?

Когда вы выполняете запрос SELECT с помощью mysqli_query(), MySQLi возвращает результирующий набор, содержащий метаданные о каждом столбце (его имя, таблицу, тип, длину и флаги). Эти метаданные читаются по одному столбцу за раз с помощью mysqli_fetch_field(), а внутренний указатель — курсор поля — отслеживает, какой столбец будет прочитан следующим.

mysqli_field_seek() позволяет переместить этот указатель к любому смещению столбца, так что следующий вызов mysqli_fetch_field() вернёт метаданные выбранного вами столбца, а не следующего по порядку.

Два понятия легко перепутать, поэтому держите их раздельно:

• Курсор поля управляет тем, метаданные какого столбца вы читаете — перемещается с помощью mysqli_field_seek().
• Курсор строки управляет тем, какую строку данных вы читаете — перемещается с помощью mysqli_data_seek().

Эта функция затрагивает только курсор поля; она никогда не изменяет то, какие строки данных возвращаются.

Синтаксис

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

В объектно-ориентированном стиле эквивалентным методом является $result->field_seek($index).

Параметры

• result — object mysqli_result, возвращённый функцией mysqli_query(), mysqli_store_result() или mysqli_use_result().
• index — нулевое смещение поля, к которому выполняется переход. Должно быть в диапазоне от 0 до количества полей минус один (см. mysqli_field_count()). Недопустимое смещение вызовет предупреждение.

Возвращаемое значение

Возвращает true. (Исторически процедурная форма документировала boolean; начиная с PHP 8.0 всегда возвращает true и генерирует ValueError при смещении вне допустимого диапазона.)

Базовое использование

Вызовите функцию на допустимом результирующем наборе, затем получите поле, метаданные которого вам нужны:

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

Здесь запрос выбирает три столбца. Смещения отсчитываются с нуля, поэтому смещение 0 соответствует id, 1 — name, 2 — email. После перехода к 2 следующий mysqli_fetch_field() вернёт метаданные столбца email.

Повторное чтение метаданных одного столбца

Практический сценарий — чтение метаданных одного и того же столбца дважды без повторного выполнения запроса. Поскольку mysqli_fetch_field() продвигает курсор вперёд, вы используете seek для его сброса:

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

Когда это использовать?

В современном коде эта функция редко нужна: большинство приложений извлекают строки в ассоциативные массивы или object с помощью mysqli_fetch_assoc() и вообще не обращают внимания на метаданные столбцов. mysqli_field_seek() полезна, когда вы:

• Создаёте универсальный инструмент (экспортёр CSV, инспектор схемы, рендерер таблицы), который проверяет столбцы по позиции.
• Читаете метаданные конкретного столбца многократно, не получая каждый раз все поля через mysqli_fetch_fields().
• Сопровождаете устаревший код, который обходит метаданные результирующего набора столбец за столбцом.

Заключение

mysqli_field_seek() перемещает курсор поля внутри результирующего набора MySQLi, чтобы следующий вызов mysqli_fetch_field() возвращал выбранный вами столбец. Функция работает только с метаданными столбцов — для перехода между строками данных используйте mysqli_data_seek(). Хотя она редко встречается в повседневном коде приложений, она удобна для инструментов, управляемых метаданными, и для понимания устаревших рабочих процессов MySQLi.

Практика