data_seek

La fonction mysqli_data_seek() en PHP déplace le pointeur interne de résultat vers une ligne arbitraire dans un ensemble de résultats mis en mémoire tampon, de sorte que le prochain appel de récupération lit à partir de cette ligne plutôt que de la suivante dans l'ordre séquentiel. Elle vous permet de sauter directement à une ligne, de relire des lignes déjà parcourues ou de recommencer depuis le début sans réexécuter la requête. Les indices de ligne sont basés sur zéro, et la fonction retourne true en cas de succès ou false en cas d'échec.

Ce chapitre couvre la signature de la fonction, les styles procédural et orienté objet, un exemple exécutable, l'exigence de résultat mis en mémoire tampon qui pose problème à la plupart des gens, et les cas où SQL LIMIT … OFFSET est le meilleur outil.

Syntaxe

// Procedural style
mysqli_data_seek(mysqli_result $result, int $offset): bool

// Object-oriented style
$result->data_seek(int $offset): bool

• $result — un ensemble de résultats retourné par mysqli_query(), mysqli_store_result() ou mysqli_use_result().
• $offset — le numéro de ligne vers lequel se déplacer, commençant à 0 pour la première ligne. Il doit être compris entre 0 et mysqli_num_rows() - 1.
• Valeur de retour — true si le déplacement réussit, false si l'offset est hors plage ou si l'ensemble de résultats n'est pas mis en mémoire tampon.

L'exigence de résultat mis en mémoire tampon

mysqli_data_seek() ne fonctionne que sur des ensembles de résultats mis en mémoire tampon — ceux dont les lignes sont déjà conservées en mémoire. C'est ce que vous obtenez avec mysqli_query() (qui appelle mysqli_store_result() en interne) et directement avec mysqli_store_result().

Si vous récupérez des lignes de manière différée avec mysqli_use_result(), les lignes sont transmises depuis le serveur une à la fois et il n'y a rien vers quoi effectuer un déplacement, donc mysqli_data_seek() échouera. Lorsque vous avez besoin d'un accès aléatoire, restez avec un résultat mis en mémoire tampon.

Comment utiliser mysqli_data_seek()

Appelez la fonction sur un ensemble de résultats valide et passez l'index de ligne sur lequel vous souhaitez vous positionner. La prochaine récupération retourne alors cette ligne :

<?php
$mysqli = mysqli_connect("localhost", "username", "password", "database");

$result = mysqli_query($mysqli, "SELECT id, name FROM users ORDER BY id");

if (!$result) {
    echo "Failed to execute query: " . mysqli_error($mysqli);
    exit();
}

// Move the pointer to row 3 (index 2, because indices are zero-based)
if (!mysqli_data_seek($result, 2)) {
    echo "Seek failed";
    exit();
}

// Fetch the row the pointer now points at
$row = mysqli_fetch_assoc($result);

print_r($row);

mysqli_free_result($result);
mysqli_close($mysqli);
?>

Nous nous connectons avec mysqli_connect(), exécutons la requête avec mysqli_query() et vérifions les erreurs. Ensuite, mysqli_data_seek($result, 2) déplace le pointeur vers la troisième ligne, et mysqli_fetch_assoc() la lit. Vérifier la valeur de retour de mysqli_data_seek() vous permet de gérer proprement un offset hors plage.

Relire un ensemble de résultats depuis le début

Une façon courante et sans base de données de voir exactement comment le pointeur se comporte est de parcourir un résultat, puis de revenir à 0 et de le parcourir à nouveau. Cet extrait utilise un array PHP simple pour modéliser la même logique de récupération puis de déplacement sans avoir besoin d'un serveur MySQL actif :

<?php
// A result set modelled as an in-memory array of rows.
$rows = [
    ['id' => 1, 'name' => 'Alice'],
    ['id' => 2, 'name' => 'Bob'],
    ['id' => 3, 'name' => 'Carol'],
];

$pointer = 0;

// "data_seek": move the pointer to an arbitrary index, like mysqli_data_seek().
function data_seek(array $rows, int $offset, int &$pointer): bool
{
    if ($offset < 0 || $offset >= count($rows)) {
        return false;
    }
    $pointer = $offset;
    return true;
}

// First pass: read every row sequentially.
echo "First pass:\n";
while ($pointer < count($rows)) {
    echo $rows[$pointer]['name'] . "\n";
    $pointer++;
}

// Rewind to the top and read again.
data_seek($rows, 0, $pointer);

echo "Second pass (after seek to 0):\n";
echo $rows[$pointer]['name'] . "\n"; // Alice again
?>

Cela affiche :

First pass:
Alice
Bob
Carol
Second pass (after seek to 0):
Alice

Avec un vrai mysqli_result, vous remplaceriez la logique du array par mysqli_data_seek($result, 0) suivi de mysqli_fetch_assoc($result) pour rembobiner un résultat mis en mémoire tampon sans réexécuter la requête.

Quand utiliser LIMIT/OFFSET à la place

mysqli_data_seek() sert à naviguer dans un ensemble de résultats que vous avez déjà téléchargé. Si votre objectif est de récupérer uniquement une partie d'une grande table, ne chargez pas toutes les lignes dans PHP juste pour effectuer un déplacement — confiez le travail à la base de données avec LIMIT et OFFSET :

SELECT id, name FROM users ORDER BY id LIMIT 10 OFFSET 20;

Cela retourne uniquement les 10 lignes souhaitées, économisant la mémoire et le trafic réseau. Réservez mysqli_data_seek() aux cas où vous avez réellement besoin d'un accès aléatoire sur un ensemble de résultats déjà en mémoire — par exemple, pour relire des lignes antérieures au cours d'une même requête.

Conclusion

mysqli_data_seek() repositionne le pointeur interne d'un ensemble de résultats mis en mémoire tampon afin que vous puissiez sauter à n'importe quelle ligne basée sur zéro, y compris en revenant au début. Retenez ses deux contraintes : l'offset doit être dans la plage (0 … num_rows - 1) et le résultat doit être mis en mémoire tampon. Pour réduire les grands ensembles de données, préférez SQL LIMIT/OFFSET ; pour vous déplacer dans des données déjà en mémoire, mysqli_data_seek() est le bon outil.

Fonctions associées : mysqli_fetch_assoc(), mysqli_fetch_array(), mysqli_fetch_row() et mysqli_query().

Pratique