Guia Completo sobre a Função mysqli_warning_count em PHP

Ao trabalhar com bancos de dados MySQL em PHP, a extensão mysqli oferece diversas funções para operações de banco de dados. Uma dessas funções é mysqli_warning_count, que foi descontinuada no PHP 8.0 e removida no PHP 8.1. Anteriormente, ela retornava o número de avisos gerados pela consulta MySQL anterior.

Este guia aborda os recursos da função e demonstra como utilizá-la de forma eficaz em seus projetos PHP.

O que é a Função mysqli_warning_count?

A função mysqli_warning_count era uma função PHP nativa que retornava o número de avisos gerados durante a execução da consulta MySQL anterior. Foi descontinuada no PHP 8.0 e removida no PHP 8.1. Diferentemente dos erros, que normalmente interrompem a execução do script, os avisos indicam problemas não fatais, como truncamento de dados ou inserções de chave duplicada, que permitem que a consulta seja concluída com sucesso.

A função aceita um argumento: o objeto de conexão MySQL retornado por mysqli_connect ou new mysqli().

Veja a sintaxe da função mysqli_warning_count:

mysqli_warning_count($connection);

Recursos da Função mysqli_warning_count

A função mysqli_warning_count oferecia uma variedade de recursos que a tornavam uma ferramenta útil para recuperar informações de avisos gerados durante a execução de consultas em bancos de dados MySQL no PHP. Alguns dos principais recursos da função incluem:

1. Recuperação do Número de Avisos

O principal recurso da função mysqli_warning_count era recuperar o número de avisos gerados durante a execução da consulta MySQL anterior. Essa informação pode ser útil para diagnosticar possíveis problemas com o servidor MySQL durante a execução de consultas.

2. Requisito de Objeto de Conexão

A função exigia um objeto de conexão MySQL válido. Era possível passar uma conexão existente para recuperar o número de avisos da consulta mais recente executada nessa conexão.

3. Conta Avisos, Não Erros

mysqli_warning_count refletia apenas avisos — condições não fatais geradas pela última instrução. Erros (que abortam a instrução) são relatados separadamente por meio de mysqli_error() / mysqli_errno(). Portanto, uma consulta pode ser concluída com sucesso e ainda assim produzir um ou mais avisos.

Como Usar a Função mysqli_warning_count

Veja alguns passos para usar a função mysqli_warning_count em seus projetos PHP:

1. Conectando ao Servidor MySQL

Antes de usar a função mysqli_warning_count, é necessário estabelecer uma conexão com o servidor MySQL utilizando a função mysqli_connect. Veja um exemplo de código:

<?php

$host = 'localhost';
$user = 'username';
$password = 'password';
$database = 'mydatabase';

$connection = mysqli_connect($host, $user, $password, $database);

if (!$connection) {
    die('Connection failed: ' . mysqli_connect_error());
}

2. Recuperando o Número de Avisos

Após estabelecer uma conexão com o servidor MySQL e executar uma consulta MySQL, você pode usar a função mysqli_warning_count para recuperar o número de avisos gerados durante a execução da consulta anterior. Veja um exemplo de código:

<?php

// Execute a query that generates a warning (e.g., duplicate key insertion)
// Assumes a table 'users' exists with a unique key on 'id'
mysqli_query($connection, "INSERT IGNORE INTO users (id, name) VALUES (1, 'Alice'), (1, 'Bob')");

// Get the number of warnings
$warning_count = mysqli_warning_count($connection);
echo "Warning count: " . $warning_count;

// Retrieve the actual warning messages
$warnings = mysqli_get_warnings($connection);
if ($warnings) {
    while ($warning = $warnings->next_warning()) {
        echo "Level: " . $warning->Level . ", Message: " . $warning->Message . "\n";
    }
}

Este código recupera o número de avisos gerados durante a execução da consulta MySQL anterior usando a função mysqli_warning_count e demonstra como buscar as mensagens de aviso detalhadas com mysqli_get_warnings().

Uma execução típica do trecho acima imprime algo como:

Warning count: 1
Level: Note, Message: Duplicate entry '1' for key 'PRIMARY'

A Substituição Moderna (PHP 8.1+)

Como mysqli_warning_count não existe mais no PHP 8.1 e versões posteriores, use a propriedade de conexão $mysqli->warning_count para ler o número, e mysqli_get_warnings() (ainda disponível) para ler os detalhes:

<?php

$mysqli = new mysqli('localhost', 'username', 'password', 'mydatabase');

$mysqli->query("INSERT IGNORE INTO users (id, name) VALUES (1, 'Alice'), (1, 'Bob')");

// Property replacing the removed mysqli_warning_count() function
echo "Warning count: " . $mysqli->warning_count . "\n";

if ($warnings = $mysqli->get_warnings()) {
    do {
        echo "Code {$warnings->errno}: {$warnings->message}\n";
    } while ($warnings->next());
}

Para novos projetos, recomenda-se habilitar o relatório baseado em exceções para que os erros lancem mysqli_sql_exception e nunca passem silenciosamente:

<?php

mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);

Conclusão

Em resumo, mysqli_warning_count anteriormente oferecia uma maneira direta de verificar avisos do MySQL após a execução de consultas. No entanto, como foi removida no PHP 8.1, o desenvolvimento moderno em PHP normalmente depende do tratamento de erros baseado em exceções (mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT)) para um gerenciamento robusto de erros. Se você estiver mantendo bases de código legadas, ainda pode usar mysqli_get_warnings() para inspecionar detalhes específicos de avisos do servidor MySQL.

Prática