error

Neste artigo, vamos focar na função mysqli_error() do PHP, usada para recuperar a mensagem de erro da última chamada de função MySQLi. Esta página aborda a sintaxe da função, seus parâmetros e valor de retorno, percorre exemplos práticos e aponta funções relacionadas ao tratamento de erros.

Introdução à função mysqli_error()

A função mysqli_error() é uma função nativa do PHP que retorna uma string descrevendo o erro da operação MySQLi mais recente realizada em uma determinada conexão. Se a última chamada teve sucesso — ou nenhuma operação foi executada ainda — ela retorna uma string vazia ("").

Você precisa dela porque a maioria das funções MySQLi (como mysqli_query()) sinaliza falha apenas retornando false. Isso indica que algo deu errado, mas não o quê. A mysqli_error() preenche essa lacuna fornecendo a mensagem legível por humanos reportada pelo servidor MySQL, por exemplo, Table 'database.my_table' doesn't exist.

Sintaxe

mysqli_error(mysqli $mysqli): string

Parâmetro

• $mysqli (obrigatório) — Um object de conexão MySQLi retornado por mysqli_connect() (ou mysqli_init() + mysqli_real_connect()). O erro reportado pertence a essa conexão específica.

Valor de retorno

Uma string com a descrição do erro para a última operação em $mysqli. Uma string vazia significa que não houve erro. Como uma string vazia é "falsy" em PHP, você normalmente ramifica o código com base no resultado da chamada que falhou (como !$result) em vez de usar a própria mysqli_error().

Estilo orientado a objeto vs. procedural. Esta página usa o estilo procedural, mysqli_error($mysqli). Com a API orientada a objetos, o equivalente é a propriedade somente leitura $mysqli->error.

Como usar a função mysqli_error()

Usar a função mysqli_error() é simples. Você a chama em um object de conexão MySQLi válido. Veja um exemplo:

Como usar a função mysqli_error()?

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

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

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

mysqli_close($mysqli);
?>

Neste exemplo, chamamos a função mysqli_connect() para conectar a um banco de dados MySQL. Em seguida, executamos uma consulta usando a função mysqli_query() e armazenamos o resultado em uma variável. Verificamos se houve um erro na consulta usando a condição !$result. Se houver um erro, passamos o object de conexão para mysqli_error() para recuperar a mensagem de erro específica, exibi-la e encerrar o script.

Nota: Sempre verifique se mysqli_connect() retorna um object válido antes de executar consultas. Se a conexão falhar, mysqli_query() disparará um aviso PHP.

Uso avançado

A função mysqli_error() também pode ser usada com múltiplas conexões. Veja um exemplo:

Uso avançado do PHP mysqli_error()

<?php
$mysqli1 = mysqli_connect("localhost", "username", "password", "database1");
$mysqli2 = mysqli_connect("localhost", "username", "password", "database2");

$query = "SELECT * FROM my_table";
$result1 = mysqli_query($mysqli1, $query);
$result2 = mysqli_query($mysqli2, $query);

if (!$result1) {
    $error_msg = mysqli_error($mysqli1);
    echo "Failed to execute query on connection 1. Error message: " . $error_msg;
    exit();
}

if (!$result2) {
    $error_msg = mysqli_error($mysqli2);
    echo "Failed to execute query on connection 2. Error message: " . $error_msg;
    exit();
}

mysqli_close($mysqli1);
mysqli_close($mysqli2);
?>

Neste exemplo, estabelecemos duas conexões separadas e executamos a mesma consulta em cada uma. Verificamos o resultado de cada conexão de forma independente. Se uma consulta falhar, passamos o object de conexão correspondente para mysqli_error() para isolar e exibir o erro específico. Isso é importante porque mysqli_error() é limitada ao escopo da conexão — chamá-la em $mysqli1 nunca reportará um erro que ocorreu em $mysqli2.

Tratamento de erros moderno com exceções

Para aplicações PHP mais recentes, considere habilitar o tratamento de erros baseado em exceções em vez de verificar mysqli_error() após cada chamada. Adicione esta linha antes de conectar:

<?php
mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);

try {
    $mysqli = mysqli_connect("localhost", "username", "password", "database");
    $result = mysqli_query($mysqli, "SELECT * FROM my_table");
} catch (mysqli_sql_exception $e) {
    echo "Database error: " . $e->getMessage();
}
?>

Com MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT definido, uma conexão ou consulta que falha automaticamente lança um object mysqli_sql_exception em vez de retornar false. A mesma mensagem que você teria lido de mysqli_error() está disponível por meio de $e->getMessage(). A partir do PHP 8.1, esse modo de relatório é o padrão, portanto a maioria do código moderno usa try/catch em vez de verificações manuais.

Problemas comuns

• Passar a conexão errada. mysqli_error() reporta erros para a conexão que você passa. Passe o mesmo $mysqli que usou para a consulta que falhou.
• Chamá-la após mysqli_close(). Uma vez que a conexão é fechada, o object não é mais válido e você não pode ler seu erro.
• Falhas de conexão. Se o próprio mysqli_connect() falhar, ele retorna false (ou lança uma exceção, no modo strict). Use mysqli_connect_error() para erros de conexão — mysqli_error() é para erros após uma conexão bem-sucedida.

Conclusão

Em conclusão, a função mysqli_error() é uma ferramenta prática para depurar e tratar erros MySQLi. Ao verificar a validade da conexão e entender como recuperar mensagens de erro específicas, você pode criar interações com banco de dados mais resilientes.

Funções relacionadas

• mysqli_query() — executa uma consulta cuja falha você inspecionará.
• mysqli_connect_error() — mensagem de erro de uma tentativa de conexão malsucedida.
• mysqli_connect_errno() — código de erro numérico para uma conexão malsucedida.
• Visão geral do PHP MySQLi — a extensão MySQLi completa.
• try/catch e exceções — tratamento de erros baseado em exceções.

Prática