error_list

A função mysqli_error_list() retorna um array dos erros gerados pela chamada mais recente da função MySQLi em uma determinada conexão. Ao contrário de mysqli_error(), que fornece apenas a última mensagem de erro como uma string, mysqli_error_list() retorna todos os erros dessa operação — cada um como um array associativo contendo o número do erro, o código SQLSTATE e a mensagem legível por humanos. Esta página explica a sintaxe, a estrutura dos dados retornados e como utilizá-la na prática.

Sintaxe

mysqli_error_list(mysqli $mysql): array

O estilo orientado a objetos utiliza a propriedade somente leitura error_list:

$mysqli->error_list;

Parâmetros

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

Valor de retorno

Um array de arrays associativos. O array é vazio quando nenhum erro ocorreu. Cada entrada possui três chaves:

Exemplo básico

Chame mysqli_error_list() logo após a operação que deseja inspecionar — normalmente quando uma consulta acabou de falhar:

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

$query = "SELECT * FROM my_table";
$result = mysqli_query($mysqli, $query);

if (!$result) {
    $error_list = mysqli_error_list($mysqli);
    foreach ($error_list as $error) {
        echo "Failed to execute query. Error message: " . $error['error'] . "\n";
    }
    exit();
}

mysqli_close($mysqli);
?>

Aqui nos conectamos, executamos uma consulta e verificamos o resultado. Se mysqli_query() retornar false, chamamos mysqli_error_list() e percorremos o array retornado, exibindo a mensagem error de cada erro antes de encerrar. Quando a consulta é bem-sucedida, o loop simplesmente não é executado porque o array está vazio.

Lendo o código de erro e o SQLSTATE

Como cada entrada é um array associativo, você pode ler o código numérico e o SQLSTATE junto com a mensagem — útil para ramificar em falhas específicas em vez de analisar o texto da mensagem:

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

$query = "SELECT * FROM my_table";
$result = mysqli_query($mysqli, $query);

if (!$result) {
    $error_list = mysqli_error_list($mysqli);
    foreach ($error_list as $error) {
        echo "Failed to execute query. Error message: " . $error['error'] . "\n";
        echo "Error code: " . $error['errno'] . "\n";
        echo "SQLSTATE error code: " . $error['sqlstate'] . "\n";
    }
    exit();
}

mysqli_close($mysqli);
?>

Este exemplo estende o básico exibindo o errno numérico e o código sqlstate de cada erro, fornecendo o contexto de diagnóstico completo.

Estilo orientado a objetos

Se você criar a conexão com new mysqli(), utilize a propriedade error_list:

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

if (!$mysqli->query("SELECT * FROM missing_table")) {
    foreach ($mysqli->error_list as $error) {
        echo "[{$error['errno']}] {$error['sqlstate']}: {$error['error']}\n";
    }
}

$mysqli->close();
?>

mysqli_error_list() vs. funções relacionadas

• mysqli_error() — retorna apenas a mensagem do último erro como uma string. Use quando precisar de uma única mensagem.
• mysqli_errno() — retorna o número do erro da última chamada.
• mysqli_error_list() — retorna todos os erros da última chamada, cada um com errno, sqlstate e error. Use quando uma única operação pode revelar múltiplos problemas.

Armadilhas

• A lista reflete apenas a chamada MySQLi mais recente naquela conexão. Capture-a imediatamente após a operação que falhou — uma chamada bem-sucedida subsequente a limpa.
• Uma operação bem-sucedida retorna um array vazio, não false ou null, portanto proteja com if (!$result) (ou verifique mysqli_errno()) antes de presumir que há erros para ler.
• Para falhas de conexão, a própria etapa de conexão falha antes que você tenha um objeto utilizável — use mysqli_connect_error() nesses casos.

Conclusão

mysqli_error_list() fornece acesso estruturado a todos os erros da última operação MySQLi, completo com número de erro, SQLSTATE e mensagem. Utilize-a quando precisar de diagnósticos mais ricos do que mysqli_error() oferece. Para um tratamento de erros PHP mais abrangente, consulte tratamento de erros PHP e a visão geral do mysqli.

Prática