affected_rows

La fonction mysqli_affected_rows() vous indique combien de lignes la dernière écriture a réellement modifiées — les lignes touchées par le dernier INSERT, UPDATE, DELETE ou REPLACE exécuté sur une connexion. C'est la méthode standard pour confirmer qu'une écriture a produit l'effet attendu : la mise à jour a-t-elle correspondu à des lignes ? la suppression a-t-elle retiré quelque chose ? Cette page couvre la syntaxe, les valeurs de retour, les styles orienté objet et procédural, un exemple complet exécutable, ainsi que les pièges courants.

Syntaxe

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

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

Le seul argument est la connexion MySQLi sur laquelle la requête a été exécutée — pas un jeu de résultats. Il n'existe aucun autre paramètre : la fonction rapporte toujours le résultat de la dernière instruction exécutée sur cette connexion.

Valeur de retour

Sur les systèmes 64 bits, le compteur peut dépasser PHP_INT_MAX, auquel cas la valeur est retournée sous forme de string numérique — c'est pourquoi le type de retour est int|string.

Piège — "correspondance" vs "modification". Pour un UPDATE, MySQL compte les lignes dont les valeurs ont réellement changé, et non celles qui correspondent simplement à la clause WHERE. Mettre une colonne à la valeur qu'elle possède déjà compte comme 0 ligne affectée. Pour compter les lignes correspondantes plutôt que modifiées, connectez-vous avec l'option MYSQLI_CLIENT_FOUND_ROWS.

Orienté objet vs. procédural

Les deux styles lisent la même valeur ; choisissez-en un et restez cohérent. Notez qu'en style OOP, affected_rows est une propriété, sans parenthèses :

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

Exemple complet

Ce script se connecte, exécute un UPDATE et indique combien de lignes ont été modifiées. Remplacez les identifiants par les vôtres.

<?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 un utilisateur avec id = 1 existe et que son nom n'était pas déjà John, la sortie est :

Rows updated: 1

Si aucun utilisateur n'a id = 1, ou si le nom était déjà John, la sortie est Rows updated: 0. Consultez mysqli_query() pour savoir comment la requête est exécutée, et mysqli_connect() pour les détails de connexion.

Avec les requêtes préparées

Lorsque vous utilisez des requêtes préparées (la méthode recommandée pour exécuter des requêtes avec des données utilisateur — voir mysqli prepared statements), appelez affected_rows sur la connexion, pas sur la déclaration, aprè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();
?>

Requêtes SELECT et compteurs obsolètes

mysqli_affected_rows() est destinée aux requêtes d'écriture. Pour un SELECT, elle retourne -1 ; pour compter les lignes d'un jeu de résultats, utilisez mysqli_num_rows() sur ce résultat à la place. Évitez l'ancienne paire SQL_CALC_FOUND_ROWS / FOUND_ROWS() — elle est dépréciée depuis MySQL 8.0.17 et supprimée dans les versions récentes. Exécutez une requête COUNT(*) séparée lorsque vous avez besoin d'un total.

Fonctions connexes

• mysqli_query() — exécuter la requête dont vous mesurez l'effet.
• mysqli_insert_id() — obtenir l'ID auto-incrémenté généré par le dernier INSERT.
• Insérer des données dans MySQL, Mettre à jour des données, Supprimer des données — guides complets CRUD.

Résumé

Utilisez mysqli_affected_rows() (ou la propriété OOP $mysqli->affected_rows) immédiatement après un INSERT, UPDATE, DELETE ou REPLACE pour vérifier l'écriture. Retenez les trois valeurs de retour — un nombre positif, 0 pour aucun changement, et -1 pour un échec ou un SELECT — et n'oubliez pas qu'un UPDATE ne compte que les lignes dont les valeurs ont vraiment changé.

Pratique