affected_rows

La función mysqli_affected_rows() te indica cuántas filas cambió realmente la última escritura — las filas modificadas por el INSERT, UPDATE, DELETE o REPLACE más reciente ejecutado en una conexión. Es la forma estándar de confirmar que una escritura hizo lo esperado: ¿la actualización coincidió con alguna fila? ¿el borrado eliminó algo? Esta página cubre la sintaxis, los valores de retorno, los estilos orientado a objetos y procedimental, un ejemplo completo ejecutable y los errores comunes que suelen confundir a los desarrolladores.

Sintaxis

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

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

El único argumento es la conexión MySQLi sobre la que ejecutaste la consulta — no un conjunto de resultados. No hay otros parámetros: la función siempre informa sobre la instrucción más reciente ejecutada en esa conexión.

Valor de retorno

En sistemas de 64 bits el recuento puede superar PHP_INT_MAX, en cuyo caso el valor se devuelve como una string numérica — por eso el tipo de retorno es int|string.

Advertencia — "coincidencia" vs "cambio". Para un UPDATE, MySQL cuenta las filas cuyos valores realmente cambiaron, no las filas que simplemente coincidieron con la cláusula WHERE. Establecer una columna con el valor que ya tenía cuenta como 0 filas afectadas. Para contar filas coincidentes en su lugar, conéctate con el indicador MYSQLI_CLIENT_FOUND_ROWS.

Orientado a objetos vs. procedimental

Ambos estilos leen el mismo valor; elige uno y mantén la coherencia. Ten en cuenta que en el estilo OOP affected_rows es una propiedad, sin paréntesis:

<?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

Un ejemplo completo

Este script se conecta, ejecuta un UPDATE e informa cuántas filas se modificaron. Reemplaza las credenciales por las tuyas.

<?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();
?>

Si existe un usuario con id = 1 y su nombre no era ya John, la salida es:

Rows updated: 1

Si ningún usuario tiene id = 1, o el nombre ya era John, la salida es Rows updated: 0. Consulta mysqli_query() para saber cómo se ejecuta la consulta en sí, y mysqli_connect() para los detalles de la conexión.

Con sentencias preparadas

Cuando usas sentencias preparadas (la forma recomendada de ejecutar consultas con entrada del usuario — consulta las sentencias preparadas de mysqli), llama a affected_rows en la conexión, no en la sentencia, después de 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 y contadores obsoletos

mysqli_affected_rows() está pensada para consultas de escritura. Para un SELECT devuelve -1; para contar filas en un conjunto de resultados, llama a mysqli_num_rows() sobre ese resultado en su lugar. Evita el antiguo par SQL_CALC_FOUND_ROWS / FOUND_ROWS() — están obsoletos desde MySQL 8.0.17 y eliminados en versiones más recientes. Ejecuta una consulta COUNT(*) separada cuando necesites un total.

Funciones relacionadas

• mysqli_query() — ejecuta la consulta cuyo efecto estás midiendo.
• mysqli_insert_id() — obtiene el ID de autoincremento generado por el último INSERT.
• Insertar datos en MySQL, Actualizar datos, Eliminar datos — guías completas de CRUD.

Resumen

Usa mysqli_affected_rows() (o la propiedad OOP $mysqli->affected_rows) justo después de un INSERT, UPDATE, DELETE o REPLACE para verificar la escritura. Recuerda los tres valores de retorno — un recuento positivo, 0 para ningún cambio y -1 para un error o un SELECT — y que un UPDATE solo cuenta las filas cuyos valores realmente cambiaron.

Práctica