field_seek

Dieser Artikel behandelt die Funktion mysqli_field_seek() in PHP, die den Feldcursor auf einen bestimmten Feldoffset in einem MySQLi-Ergebnissatz setzt. Wir erklären, was der Feldcursor ist, wann man diese Funktion einsetzt, dokumentieren ihre Parameter und den Rückgabewert und gehen anhand von Beispielen durch die praktische Anwendung.

Was ist der Feldcursor?

Wenn Sie eine SELECT-Abfrage mit mysqli_query() ausführen, gibt MySQLi einen Ergebnissatz zurück, der Metadaten zu jeder Spalte enthält (Name, Tabelle, Typ, Länge und Flags). Diese Metadaten werden Spalte für Spalte mit mysqli_fetch_field() gelesen, und ein interner Zeiger — der Feldcursor — verfolgt, welche Spalte als nächstes gelesen wird.

Mit mysqli_field_seek() können Sie diesen Zeiger auf einen beliebigen Spaltenoffset verschieben, sodass der nächste Aufruf von mysqli_fetch_field() die Metadaten der von Ihnen gewählten Spalte zurückgibt, anstatt der nächsten in der Reihenfolge.

Zwei Dinge werden leicht verwechselt — halten Sie sie daher auseinander:

• Der Feldcursor steuert, welche Spaltenmetadaten Sie lesen — verschoben mit mysqli_field_seek().
• Der Zeilencursor steuert, welche Datenzeile Sie lesen — verschoben mit mysqli_data_seek().

Diese Funktion wirkt sich nur auf den Feldcursor aus; sie ändert nie, welche Datenzeilen zurückgegeben werden.

Syntax

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

Im objektorientierten Stil lautet die entsprechende Methode $result->field_seek($index).

Parameter

• result — Ein mysqli_result-object, das von mysqli_query(), mysqli_store_result() oder mysqli_use_result() zurückgegeben wurde.
• index — Der nullbasierte Feldoffset, zu dem gesprungen werden soll. Er muss zwischen 0 und der Anzahl der Felder minus eins liegen (siehe mysqli_field_count()). Ein ungültiger Offset löst eine Warnung aus.

Rückgabewert

Gibt true zurück. (Historisch dokumentierte die prozedurale Form einen boolean; seit PHP 8.0 gibt sie immer true zurück und wirft bei einem Offset außerhalb des gültigen Bereichs einen ValueError.)

Grundlegende Verwendung

Rufen Sie die Funktion auf einem gültigen Ergebnissatz auf und holen Sie dann das Feld ab, dessen Metadaten Sie benötigen:

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

Die Abfrage wählt hier drei Spalten aus. Offsets sind nullbasiert, daher ist Offset 0 gleich id, 1 gleich name und 2 gleich email. Nach dem Sprung zu 2 gibt das nächste mysqli_fetch_field() die Metadaten der Spalte email zurück.

Metadaten einer einzelnen Spalte erneut lesen

Ein praktischer Anwendungsfall ist das zweifache Lesen der Metadaten derselben Spalte, ohne die Abfrage erneut auszuführen. Da mysqli_fetch_field() den Cursor vorschiebt, springen Sie zurück, um ihn zurückzusetzen:

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

Wann würde ich das verwenden?

In modernem Code wird diese Funktion selten benötigt: Die meisten Anwendungen holen Zeilen als assoziative Arrays oder Objekte mit mysqli_fetch_assoc() und ignorieren Spaltenmetadaten vollständig. mysqli_field_seek() ist nützlich, wenn Sie:

• Ein generisches Werkzeug erstellen (einen CSV-Exporteur, einen Schema-Inspektor, einen Grid-Renderer), das Spalten nach Position untersucht.
• Die Metadaten einer bestimmten Spalte wiederholt lesen, ohne alle Felder mit mysqli_fetch_fields() erneut abzurufen.
• Legacy-Code pflegen, der Metadaten eines Ergebnissatzes Spalte für Spalte durchläuft.

Fazit

mysqli_field_seek() positioniert den Feldcursor innerhalb eines MySQLi-Ergebnissatzes neu, sodass der nächste Aufruf von mysqli_fetch_field() die von Ihnen gewählte Spalte zurückgibt. Die Funktion wirkt ausschließlich auf Spaltenmetadaten — um zwischen Datenzeilen zu wechseln, verwenden Sie stattdessen mysqli_data_seek(). In alltäglichem Anwendungscode ist sie zwar selten anzutreffen, erweist sich aber für metadatengesteuerte Werkzeuge und das Verständnis älterer MySQLi-Workflows als praktisch.

Übungen