field_seek

Questo articolo tratta la funzione mysqli_field_seek() in PHP, che sposta il cursore di campo a un offset specificato all'interno di un result set MySQLi. Spiegheremo cos'è il cursore di campo, quando è utile ricorrere a questa funzione, ne documenteremo i parametri e il valore restituito e analizzeremo esempi pratici.

Cos'è il cursore di campo?

Quando si esegue una query SELECT con mysqli_query(), MySQLi restituisce un result set che contiene metadati su ciascuna colonna (nome, tabella, tipo, lunghezza e flag). Questi metadati vengono letti una colonna alla volta tramite mysqli_fetch_field(), e un puntatore interno — il cursore di campo — tiene traccia di quale colonna verrà letta successivamente.

mysqli_field_seek() consente di spostare quel puntatore a qualsiasi offset di colonna, in modo che la chiamata successiva a mysqli_fetch_field() restituisca i metadati della colonna scelta anziché quella successiva in sequenza.

È facile confondere due concetti, quindi tenerli separati:

• Il cursore di campo controlla i metadati della colonna che si legge — spostato con mysqli_field_seek().
• Il cursore di riga controlla quale riga di dati si legge — spostato con mysqli_data_seek().

Questa funzione agisce solo sul cursore di campo; non modifica mai le righe di dati restituite.

Sintassi

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

Nello stile orientato agli oggetti il metodo equivalente è $result->field_seek($index).

Parametri

• result — Un object mysqli_result restituito da mysqli_query(), mysqli_store_result() o mysqli_use_result().
• index — L'offset di campo (a base zero) verso cui spostarsi. Deve essere compreso tra 0 e il numero di campi meno uno (vedere mysqli_field_count()). Un offset non valido genera un avviso.

Valore restituito

Restituisce true. (Storicamente la forma procedurale documentava un boolean; a partire da PHP 8.0 restituisce sempre true e genera un ValueError per un offset fuori range.)

Utilizzo di base

Chiama la funzione su un result set valido, quindi recupera i metadati del campo desiderato:

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

In questo esempio la query seleziona tre colonne. Gli offset sono a base zero, quindi offset 0 è id, 1 è name e 2 è email. Dopo essersi posizionati su 2, la successiva mysqli_fetch_field() restituisce i metadati della colonna email.

Ri-lettura dei metadati di una singola colonna

Un utilizzo pratico è la lettura dei metadati della stessa colonna due volte senza dover rieseguire la query. Poiché mysqli_fetch_field() avanza il cursore, è sufficiente tornare indietro con seek per reimpostarlo:

<?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 usare questa funzione?

Nel codice moderno raramente è necessaria: la maggior parte delle applicazioni recupera le righe in array associativi o object con mysqli_fetch_assoc() e ignora completamente i metadati delle colonne. mysqli_field_seek() è utile quando si sta:

• Costruendo uno strumento generico (un esportatore CSV, un ispettore di schema, un renderer a griglia) che esamina le colonne per posizione.
• Leggendo i metadati di una colonna specifica più volte senza dover recuperare tutti i campi con mysqli_fetch_fields().
• Manutenendo codice legacy che scorre i metadati del result set colonna per colonna.

Conclusione

mysqli_field_seek() riposiziona il cursore di campo all'interno di un result set MySQLi in modo che la successiva chiamata a mysqli_fetch_field() restituisca la colonna scelta. Agisce solo sui metadati delle colonne — per spostarsi tra le righe di dati, usa invece mysqli_data_seek(). Pur essendo poco comune nel codice applicativo quotidiano, è comoda per strumenti basati sui metadati e per comprendere i flussi di lavoro MySQLi legacy.

Esercitazione