field_seek

Cet article traite de la fonction mysqli_field_seek() en PHP, qui positionne le curseur de champ sur un offset de champ spécifié dans un ensemble de résultats MySQLi. Nous expliquerons ce qu'est le curseur de champ, dans quels cas vous utiliseriez cette fonction, documenterons ses paramètres et sa valeur de retour, et passerons en revue des exemples concrets.

Qu'est-ce que le curseur de champ ?

Lorsque vous exécutez une requête SELECT avec mysqli_query(), MySQLi renvoie un ensemble de résultats contenant des métadonnées sur chaque colonne (son nom, sa table, son type, sa longueur et ses indicateurs). Ces métadonnées sont lues colonne par colonne à l'aide de mysqli_fetch_field(), et un pointeur interne — le curseur de champ — suit quelle colonne sera lue ensuite.

mysqli_field_seek() vous permet de déplacer ce pointeur vers n'importe quel offset de colonne, de sorte que le prochain appel à mysqli_fetch_field() retourne les métadonnées de la colonne que vous avez choisie plutôt que la suivante dans la séquence.

Deux choses sont faciles à confondre, gardez-les bien distinctes :

• Le curseur de champ contrôle les métadonnées de quelle colonne vous lisez — déplacé avec mysqli_field_seek().
• Le curseur de ligne contrôle quelle ligne de données vous lisez — déplacé avec mysqli_data_seek().

Cette fonction agit uniquement sur le curseur de champ ; elle ne modifie jamais les lignes de données retournées.

Syntaxe

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

En style orienté objet, la méthode équivalente est $result->field_seek($index).

Paramètres

• result — Un object mysqli_result retourné par mysqli_query(), mysqli_store_result(), ou mysqli_use_result().
• index — L'offset de champ base zéro vers lequel se positionner. Il doit être compris entre 0 et le nombre de champs moins un (voir mysqli_field_count()). Un offset invalide déclenche un avertissement.

Valeur de retour

Retourne true. (Historiquement, la forme procédurale documentait un boolean ; depuis PHP 8.0, elle retourne toujours true et lève une ValueError pour un offset hors limites.)

Utilisation de base

Appelez la fonction sur un ensemble de résultats valide, puis récupérez les métadonnées du champ souhaité :

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

Ici, la requête sélectionne trois colonnes. Les offsets sont base zéro, donc l'offset 0 correspond à id, 1 à name et 2 à email. Après le positionnement sur 2, le prochain mysqli_fetch_field() retourne les métadonnées de la colonne email.

Relire les métadonnées d'une seule colonne

Une utilisation pratique consiste à lire les métadonnées d'une même colonne deux fois sans relancer la requête. Comme mysqli_fetch_field() avance le curseur, vous revenez en arrière avec seek pour le réinitialiser :

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

Quand utiliser cette fonction ?

Dans le code moderne, vous en avez rarement besoin : la plupart des applications récupèrent les lignes dans des tableaux associatifs ou des objets avec mysqli_fetch_assoc() et ignorent entièrement les métadonnées des colonnes. mysqli_field_seek() est utile lorsque vous :

• Construisez un outil générique (un exportateur CSV, un inspecteur de schéma, un moteur de rendu de grille) qui inspecte les colonnes par position.
• Lisez les métadonnées d'une colonne spécifique à plusieurs reprises sans récupérer tous les champs avec mysqli_fetch_fields().
• Maintenez du code hérité qui parcourt les métadonnées d'un ensemble de résultats colonne par colonne.

Conclusion

mysqli_field_seek() repositionne le curseur de champ dans un ensemble de résultats MySQLi afin que le prochain appel à mysqli_fetch_field() retourne la colonne de votre choix. Elle agit uniquement sur les métadonnées des colonnes — pour naviguer entre les lignes de données, utilisez mysqli_data_seek() à la place. Bien qu'elle soit peu courante dans le code applicatif quotidien, elle est pratique pour les outils pilotés par des métadonnées et pour comprendre les flux de travail MySQLi hérités.

Pratique