more_results

A função mysqli_more_results() verifica se outro conjunto de resultados ainda está aguardando após você executar várias instruções SQL de uma vez com mysqli_multi_query(). Ela é uma parte do pequeno conjunto de ferramentas usado para percorrer os resultados de uma consulta com múltiplas instruções. Este artigo explica sua sintaxe, valor de retorno, o padrão de loop ao qual pertence e os problemas comuns que surgem.

Sintaxe

mysqli_more_results(mysqli $mysql): bool

No estilo orientado a objetos, o mesmo método é $mysqli->more_results().

Parâmetro

• $mysql — um objeto de conexão MySQLi retornado por mysqli_connect() (ou new mysqli(...)).

Valor de retorno

mysqli_more_results() retorna true se um ou mais conjuntos de resultados ainda estiverem disponíveis da última chamada a mysqli_multi_query(), e false se não houver mais. Ela não avança para o próximo conjunto — para isso você chama mysqli_next_result().

Quando devo usá-la?

Uma única mysqli_query() retorna um conjunto de resultados, portanto você nunca precisa de mysqli_more_results() nesse caso. Ela só importa com mysqli_multi_query(), que permite enviar várias instruções separadas por ; em uma única viagem de ida e volta — por exemplo, uma chamada de stored procedure que retorna múltiplos SELECTs, ou um script de importação em lote. mysqli_more_results() é a condição de loop que indica quando parar.

O padrão de loop padrão

Três funções trabalham juntas:

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

Para as três instruções acima, isso imprime:

Result: 1
Result: 2
Result: 3

O do...while (não um simples while) é intencional: o primeiro conjunto de resultados já está disponível logo após mysqli_multi_query(), portanto você deve processá-lo antes de verificar se há mais.

Problemas comuns

• Sempre combine com mysqli_next_result(). mysqli_more_results() apenas informa o estado; ela nunca move o ponteiro. Chamá-la em um loop sem mysqli_next_result() resulta em um loop infinito no primeiro conjunto.
• Libere cada conjunto de resultados. Chame mysqli_free_result() antes de avançar, ou você mantém conjuntos de resultados extras na memória.
• Uma instrução que não retorna linhas (um INSERT, UPDATE, ou SELECT vazio) faz mysqli_store_result() retornar false — isso é normal, não um erro. Verifique mysqli_errno($mysqli) se precisar distinguir os dois casos.

Demonstrando o valor de retorno sem um banco de dados

Você não precisa de um servidor em execução para ver o que a função reporta. Espelhar a lógica com um pequeno array mostra o loop e o boolean claramente:

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

Saída:

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

Funções relacionadas

• mysqli_multi_query() — executa as múltiplas instruções.
• mysqli_next_result() — avança para o próximo conjunto de resultados.
• mysqli_use_result() — uma alternativa ao store_result() que transmite as linhas.
• A visão geral da extensão MySQLi — como todas essas funções se encaixam.

Conclusão

mysqli_more_results() é a verificação "há mais?" no loop de multi-query. Por si só faz pouco; combinada com mysqli_next_result() e mysqli_store_result() em um do...while, permite processar de forma limpa cada conjunto de resultados retornado por uma única chamada a mysqli_multi_query().

Prática