errno

Este artigo aborda a função PHP mysqli_errno(), que retorna o código de erro numérico da chamada mais recente em uma conexão MySQLi. Você aprenderá o que ela retorna, como interpretar o código, como ela se diferencia de mysqli_error() e como utilizá-la nos estilos procedural e orientado a objetos do MySQLi.

O que faz mysqli_errno()

mysqli_errno() é uma função nativa do PHP que retorna o código de erro da última função MySQLi executada em uma determinada conexão. É a contrapartida programática de uma mensagem legível por humanos: enquanto mysqli_error() fornece uma frase como "Table 'db.my_table' doesn't exist", mysqli_errno() fornece o inteiro bruto (neste caso, 1146) que você pode comparar no código.

Sintaxe e valor de retorno

mysqli_errno(mysqli $mysqli): int

• Parâmetro — $mysqli: uma conexão retornada por mysqli_connect() (procedural) ou new mysqli(...) (orientado a objetos).
• Valor de retorno — o código de erro da última chamada nessa conexão, ou 0 se não ocorreu nenhum erro. Sempre verifique o valor de retorno em vez de assumir que há um erro.

Por que um número? Códigos numéricos são estáveis e fáceis de ramificar. O texto de uma mensagem de erro pode mudar entre versões do MySQL ou localidades, mas o código (por exemplo, 1062 para uma chave duplicada) permanece o mesmo — então são os códigos que você deve testar na lógica if/switch.

Usando mysqli_errno() (estilo procedural)

Ela requer uma conexão MySQLi válida como único argumento. Aqui está um padrão típico:

Como usar a função mysqli_errno()?

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

if (!$mysqli) {
    die("Connection failed: " . mysqli_connect_error());
}

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

if (!$result) {
    $error_code = mysqli_errno($mysqli);
    echo "Failed to execute query. Error code: " . $error_code;
    exit();
}

mysqli_close($mysqli);
?>

Aqui, primeiro verificamos se a conexão foi bem-sucedida, depois executamos uma consulta com mysqli_query(). Se a consulta falhar (!$result), mysqli_errno($mysqli) nos fornece o código numérico para que possamos registrá-lo e encerrar.

Combinando errno com mysqli_error()

Na prática, você quase sempre deseja tanto o código (para ramificar) quanto a mensagem (para registrar ou exibir). Use mysqli_errno() em conjunto com mysqli_error():

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

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

if (!$result) {
    $code    = mysqli_errno($mysqli);   // e.g. 1146
    $message = mysqli_error($mysqli);   // e.g. "Table 'database.missing_table' doesn't exist"

    // Branch on the stable numeric code, not the message text.
    if ($code === 1146) {
        echo "The table is missing. ";
    }
    echo "[$code] $message";
}

mysqli_close($mysqli);
?>

Estilo orientado a objetos

Se você criar a conexão com new mysqli(...), acesse $mysqli->errno como propriedade (e $mysqli->error para a mensagem) em vez da função procedural:

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

if (!$mysqli->query("SELECT * FROM missing_table")) {
    echo "Error " . $mysqli->errno . ": " . $mysqli->error;
}

$mysqli->close();
?>

Ambos os estilos reportam o mesmo código — escolha o que combina com o restante do seu código. Consulte PHP MySQLi para uma visão geral da extensão.

Códigos de erro MySQL comuns

Alguns códigos que você encontrará frequentemente ao tratar erros MySQLi:

Para a lista completa, consulte a referência oficial de erros do servidor MySQL.

Uso avançado

A função mysqli_errno() também pode ser usada em cenários mais avançados. Ao trabalhar com múltiplas conexões, você deve passar o objeto MySQLi específico para a função a fim de recuperar o código de erro daquela conexão em particular. Veja um exemplo:

Uso avançado de PHP mysqli_errno()

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

if (!$mysqli1 || !$mysqli2) {
    die("One or more connections failed.");
}

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

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

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

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

Neste exemplo, criamos dois objetos MySQLi e conectamos a dois bancos de dados MySQL diferentes. Em seguida, executamos a mesma consulta usando cada conexão e armazenamos o resultado em uma variável. Verificamos se houve um erro em cada consulta usando a condição !$result. Se houver um erro, chamamos mysqli_errno() para o objeto MySQLi relevante para obter o código de erro associado àquela conexão específica. Em seguida, exibimos o código de erro e encerramos o script.

Nota: mysqli_errno() reporta o erro de uma conexão específica. Com múltiplas conexões abertas, o código tem escopo definido pelo objeto de conexão que você passa — portanto, sempre passe o correto.

Funções relacionadas

• mysqli_connect_errno() — código de erro para uma tentativa de conexão que falhou (quando o link em si não pôde ser estabelecido).
• mysqli_connect_error() — a mensagem para uma tentativa de conexão que falhou.
• error_get_last() — o último erro PHP (não específico ao MySQLi).

Conclusão

mysqli_errno() retorna o código de erro numérico da operação mais recente em uma conexão MySQLi, ou 0 quando não houve erro. Combine-a com mysqli_error() para obter a mensagem, ramifique com base no código numérico estável e passe o objeto de conexão correto quando houver vários abertos — essa é a base de um tratamento de erros MySQLi robusto.

Prática