affected_rows

La funzione mysqli_affected_rows() indica quante righe l'ultima scrittura ha effettivamente modificato — le righe interessate dal più recente INSERT, UPDATE, DELETE o REPLACE eseguito su una connessione. È il modo standard per verificare che una scrittura abbia prodotto l'effetto atteso: l'aggiornamento ha trovato qualche riga? L'eliminazione ha rimosso qualcosa? Questa pagina tratta la sintassi, i valori di ritorno, lo stile orientato agli oggetti e lo stile procedurale, un esempio completo eseguibile e le insidie più comuni.

Sintassi

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

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

L'unico argomento è la connessione MySQLi su cui è stata eseguita la query — non un result set. Non esistono altri parametri: la funzione riporta sempre l'istruzione più recente eseguita su quella connessione.

Valore di ritorno

Sui sistemi a 64 bit il conteggio può superare PHP_INT_MAX, nel qual caso il valore viene restituito come string numerica — ecco perché il tipo di ritorno è int|string.

Attenzione — "trovate" vs "modificate". Per un UPDATE, MySQL conta le righe i cui valori sono stati effettivamente cambiati, non quelle che corrispondevano semplicemente alla clausola WHERE. Impostare una colonna sul valore che già possiede conta come 0 righe interessate. Per contare le righe trovate anziché quelle modificate, connettiti con il flag MYSQLI_CLIENT_FOUND_ROWS.

Stile orientato agli oggetti vs. procedurale

Entrambi gli stili leggono lo stesso valore; scegli uno e mantienilo coerente. Nota che nello stile OOP affected_rows è una proprietà, senza parentesi:

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

Questo script si connette, esegue un UPDATE e riporta quante righe sono state modificate. Sostituisci le credenziali con le tue.

<?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 esiste un utente con id = 1 e il suo nome non era già John, l'output è:

Rows updated: 1

Se nessun utente ha id = 1, o il nome era già John, l'output è Rows updated: 0. Consulta mysqli_query() per le modalità di esecuzione della query e mysqli_connect() per i dettagli sulla connessione.

Con le prepared statement

Quando si usano le prepared statement (il modo consigliato per eseguire query con input dell'utente — vedi mysqli prepared statements), chiama affected_rows sulla connessione, non sull'istruzione, dopo 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();
?>

Query SELECT e contatori deprecati

mysqli_affected_rows() è pensata per le query di scrittura. Per una SELECT restituisce -1; per contare le righe in un result set, chiama mysqli_num_rows() su quel risultato. Evita la coppia SQL_CALC_FOUND_ROWS / FOUND_ROWS() — sono deprecate da MySQL 8.0.17 e rimosse nelle versioni più recenti. Esegui una query COUNT(*) separata quando hai bisogno di un totale.

Funzioni correlate

• mysqli_query() — esegui la query di cui vuoi misurare l'effetto.
• mysqli_insert_id() — ottieni l'ID auto-increment generato dall'ultimo INSERT.
• Inserire dati in MySQL, Aggiornare dati, Eliminare dati — guide complete alle operazioni CRUD.

Riepilogo

Usa mysqli_affected_rows() (o la proprietà OOP $mysqli->affected_rows) subito dopo un INSERT, UPDATE, DELETE o REPLACE per verificare la scrittura. Ricorda i tre valori di ritorno — un conteggio positivo, 0 se non ci sono modifiche, e -1 in caso di errore o per una SELECT — e che un UPDATE conta solo le righe i cui valori sono stati effettivamente cambiati.

Pratica