affected_rows

Функция mysqli_affected_rows() сообщает, сколько строк последняя операция записи реально изменила — строк, затронутых самым последним INSERT, UPDATE, DELETE или REPLACE, выполненным через данное соединение. Это стандартный способ убедиться, что запись прошла так, как ожидалось: совпал ли UPDATE с какими-либо строками? Удалил ли DELETE хотя бы одну? На этой странице рассматриваются синтаксис, возвращаемые значения, объектно-ориентированный и процедурный стили, готовый сквозной пример и распространённые подводные камни.

Синтаксис

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

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

Единственный аргумент — MySQLi-соединение, через которое выполнялся запрос, а не результирующий набор. Других параметров нет: функция всегда сообщает о последнем операторе, выполненном через это соединение.

Возвращаемое значение

На 64-битных системах счётчик может превысить PHP_INT_MAX, и тогда значение возвращается в виде числовой string — именно поэтому тип возврата int|string.

Подводный камень — «найдено» против «изменено». Для UPDATE MySQL считает строки, значения которых действительно изменились, а не строки, просто совпавшие с условием WHERE. Установка столбца в то же значение, которое в нём уже хранится, считается 0 затронутых строк. Чтобы считать найденные строки вместо изменённых, подключитесь с флагом MYSQLI_CLIENT_FOUND_ROWS.

Объектно-ориентированный и процедурный стили

Оба стиля читают одно и то же значение; выберите один и придерживайтесь его. Обратите внимание: в ООП-стиле affected_rows — это свойство, без скобок:

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

Полный пример

Этот скрипт устанавливает соединение, выполняет UPDATE и сообщает, сколько строк было изменено. Замените учётные данные своими.

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

Если пользователь с id = 1 существует и его имя ещё не равно John, вывод будет таким:

Rows updated: 1

Если пользователя с id = 1 нет или его имя уже John, вывод будет Rows updated: 0. Подробнее о выполнении самого запроса см. mysqli_query(), о деталях соединения — mysqli_connect().

С подготовленными запросами

При использовании подготовленных запросов (рекомендуемый способ выполнения запросов с пользовательскими данными — см. mysqli prepared statements) вызывайте affected_rows на соединении, а не на объекте запроса, после 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();
?>

SELECT-запросы и устаревшие счётчики

mysqli_affected_rows() предназначена для запросов записи. Для SELECT она возвращает -1; чтобы подсчитать строки в результирующем наборе, вызовите mysqli_num_rows() на этом результате. Избегайте старой пары SQL_CALC_FOUND_ROWS / FOUND_ROWS() — они объявлены устаревшими начиная с MySQL 8.0.17 и удалены в более новых версиях. Для получения общего количества строк выполняйте отдельный запрос с COUNT(*).

Связанные функции

• mysqli_query() — выполнение запроса, результат которого вы измеряете.
• mysqli_insert_id() — получение автоинкрементного идентификатора, сгенерированного последним INSERT.
• Вставка данных в MySQL, Обновление данных, Удаление данных — полные руководства по CRUD-операциям.

Итог

Используйте mysqli_affected_rows() (или ООП-свойство $mysqli->affected_rows) сразу после INSERT, UPDATE, DELETE или REPLACE, чтобы убедиться в успешности записи. Помните три возможных значения: положительное число, 0 — нет изменений, -1 — ошибка или SELECT; а также то, что UPDATE считает только строки, значения которых действительно изменились.

Практика