affected_rows

A função mysqli_affected_rows() informa quantas linhas a última escrita realmente alterou — as linhas tocadas pelo INSERT, UPDATE, DELETE ou REPLACE mais recente executado em uma conexão. É a maneira padrão de confirmar que uma escrita fez o que você esperava: a atualização correspondeu a alguma linha? a exclusão removeu algo? Esta página abrange a sintaxe, os valores de retorno, os estilos orientado a objeto e procedural, um exemplo completo executável e as armadilhas que pegam as pessoas de surpresa.

Sintaxe

// Procedural style
mysqli_affected_rows(mysqli $mysql): int|string

// Object-oriented style (a read-only property, not a method call)
$mysqli->affected_rows

O único argumento é a conexão MySQLi na qual você executou a consulta — não um conjunto de resultados. Não há outros parâmetros: a função sempre reporta sobre a instrução mais recente executada nessa conexão.

Valor de retorno

Em sistemas de 64 bits, a contagem pode exceder PHP_INT_MAX; nesse caso, o valor é retornado como uma string numérica — é por isso que o tipo de retorno é int|string.

Atenção — "correspondeu" vs "alterou". Para um UPDATE, o MySQL conta as linhas cujos valores foram realmente alterados, não as linhas que simplesmente corresponderam à cláusula WHERE. Definir uma coluna para o valor que ela já possui conta como 0 linhas afetadas. Para contar linhas correspondentes em vez disso, conecte-se com o sinalizador MYSQLI_CLIENT_FOUND_ROWS.

Orientado a objeto vs. procedural

Ambos os estilos leem o mesmo valor; escolha um e mantenha a consistência. Observe que no estilo OOP affected_rows é uma propriedade, sem parênteses:

<?php
// Object-oriented
$mysqli->query("DELETE FROM users WHERE active = 0");
echo $mysqli->affected_rows;        // property — no ()

// Procedural — same result
mysqli_query($link, "DELETE FROM users WHERE active = 0");
echo mysqli_affected_rows($link);   // function call

Um exemplo completo

Este script conecta, executa um UPDATE e reporta quantas linhas foram alteradas. Substitua as credenciais pelas suas próprias.

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

if ($mysqli->connect_errno) {
    echo "Failed to connect to MySQL: " . $mysqli->connect_error;
    exit();
}

$mysqli->query("UPDATE users SET name = 'John' WHERE id = 1");
echo "Rows updated: " . mysqli_affected_rows($mysqli);

$mysqli->close();
?>

Se um usuário com id = 1 existir e seu nome não for ainda John, a saída será:

Rows updated: 1

Se nenhum usuário tiver id = 1, ou se o nome já for John, a saída será Rows updated: 0. Veja mysqli_query() para saber como a própria consulta é executada, e mysqli_connect() para os detalhes de conexão.

Com instruções preparadas

Ao usar instruções preparadas (a maneira recomendada de executar consultas com entrada do usuário — veja mysqli prepared statements), chame affected_rows na conexão, não na instrução, após execute():

<?php
$stmt = $mysqli->prepare("UPDATE users SET name = ? WHERE id = ?");
$stmt->bind_param("si", $name, $id);
$name = "John";
$id   = 1;
$stmt->execute();

echo "Rows updated: " . $mysqli->affected_rows;  // read from the connection
$stmt->close();
?>

Consultas SELECT e contadores obsoletos

mysqli_affected_rows() destina-se a consultas de escrita. Para um SELECT retorna -1; para contar linhas em um conjunto de resultados, chame mysqli_num_rows() nesse resultado. Evite o antigo par SQL_CALC_FOUND_ROWS / FOUND_ROWS() — eles foram descontinuados no MySQL 8.0.17 e removidos em versões mais recentes. Execute uma consulta COUNT(*) separada quando precisar de um total.

Funções relacionadas

• mysqli_query() — executar a consulta cujo efeito você está medindo.
• mysqli_insert_id() — obter o ID de incremento automático gerado pelo último INSERT.
• Inserir dados no MySQL, Atualizar dados, Excluir dados — tutoriais completos de CRUD.

Resumo

Use mysqli_affected_rows() (ou a propriedade OOP $mysqli->affected_rows) logo após um INSERT, UPDATE, DELETE ou REPLACE para verificar a escrita. Lembre-se dos três valores de retorno — uma contagem positiva, 0 para nenhuma alteração e -1 para uma falha ou um SELECT — e que um UPDATE conta apenas as linhas cujos valores realmente mudaram.

Prática