more_results

La fonction mysqli_more_results() vérifie si un autre ensemble de résultats est encore en attente après l'exécution de plusieurs instructions SQL à la fois avec mysqli_multi_query(). C'est l'un des éléments du petit ensemble d'outils utilisé pour parcourir les résultats d'une requête multi-instructions. Cet article explique sa syntaxe, sa valeur de retour, le modèle de boucle auquel elle appartient, ainsi que les pièges courants.

Syntaxe

mysqli_more_results(mysqli $mysql): bool

En style orienté objet, la même méthode s'écrit $mysqli->more_results().

Paramètre

• $mysql — un objet de connexion MySQLi retourné par mysqli_connect() (ou new mysqli(...)).

Valeur de retour

mysqli_more_results() retourne true si un ou plusieurs ensembles de résultats sont encore disponibles depuis le dernier appel à mysqli_multi_query(), et false s'il n'y en a plus. Elle ne passe pas à l'ensemble suivant — pour cela, vous appelez mysqli_next_result().

Quand l'utiliser ?

Un seul mysqli_query() retourne un ensemble de résultats, vous n'avez donc jamais besoin de mysqli_more_results() dans ce cas. Elle n'est utile qu'avec mysqli_multi_query(), qui permet d'envoyer plusieurs instructions séparées par ; en un seul aller-retour — par exemple un appel à une procédure stockée qui retourne plusieurs SELECT, ou un script d'import par lot. mysqli_more_results() est la condition de boucle qui indique quand s'arrêter.

Le modèle de boucle standard

Trois fonctions fonctionnent ensemble :

<?php
$mysqli = mysqli_connect("localhost", "user", "pass", "demo");

mysqli_multi_query($mysqli, "SELECT 1 AS n; SELECT 2 AS n; SELECT 3 AS n;");

do {
    // Fetch the result set for the current statement.
    if ($result = mysqli_store_result($mysqli)) {
        $row = mysqli_fetch_assoc($result);
        echo "Result: {$row['n']}\n";
        mysqli_free_result($result);
    }
    // Keep going only while another set is queued AND we can advance to it.
} while (mysqli_more_results($mysqli) && mysqli_next_result($mysqli));

mysqli_close($mysqli);
?>

Pour les trois instructions ci-dessus, cela affiche :

Result: 1
Result: 2
Result: 3

Le do...while (et non un simple while) est délibéré : le premier ensemble de résultats est déjà courant immédiatement après mysqli_multi_query(), vous devez donc le traiter avant de tester s'il y en a d'autres.

Pièges courants

• Toujours l'associer à mysqli_next_result(). mysqli_more_results() ne fait que rapporter l'état ; elle ne déplace jamais le pointeur. L'appeler dans une boucle sans mysqli_next_result() produit une boucle infinie sur le premier ensemble.
• Libérer chaque ensemble de résultats. Appelez mysqli_free_result() avant d'avancer, sinon vous conservez des ensembles de résultats supplémentaires en mémoire.
• Une instruction qui ne retourne aucune ligne (un INSERT, UPDATE, ou un SELECT vide) fait retourner false à mysqli_store_result() — c'est normal, ce n'est pas une erreur. Vérifiez mysqli_errno($mysqli) si vous avez besoin de distinguer les deux cas.

Démontrer la valeur de retour sans base de données

Vous n'avez pas besoin d'un serveur actif pour voir ce que la fonction rapporte. Reproduire la logique avec un petit tableau illustre clairement la boucle et le booléen :

<?php
$resultSets = ["one", "two", "three"];
$index = 0;

do {
    echo "Processing: {$resultSets[$index]}\n";
    $index++;
    // more_results() is true while another set remains.
    $more = $index < count($resultSets);
    echo $more ? "more_results -> true\n" : "more_results -> false\n";
} while ($more);
?>

Sortie :

Processing: one
more_results -> true
Processing: two
more_results -> true
Processing: three
more_results -> false

Fonctions associées

• mysqli_multi_query() — exécute les instructions multiples en premier lieu.
• mysqli_next_result() — avance vers l'ensemble de résultats suivant.
• mysqli_use_result() — une alternative à store_result() qui diffuse les lignes.
• Vue d'ensemble de l'extension MySQLi — comment toutes ces fonctions s'articulent ensemble.

Conclusion

mysqli_more_results() est la vérification « y a-t-il encore des données ? » dans la boucle multi-requêtes. Seule, elle fait peu de chose ; combinée à mysqli_next_result() et mysqli_store_result() dans un do...while, elle permet de traiter proprement chaque ensemble de résultats retourné par un seul appel à mysqli_multi_query().

Pratique