mysqli_stmt_affected_rows — Funktion · PHP-Referenz

Signatur

mysqli_stmt_affected_rows(mysqli_stmt $statement): int|string

Beschreibung

mysqli_stmt_affected_rows() liefert die Anzahl der Zeilen, die von einem INSERT-, UPDATE-, DELETE- oder REPLACE-Statement betroffen waren, das zuvor über ein Prepared Statement ausgeführt wurde. Die Funktion ist das Pendant zu mysqli_affected_rows(), arbeitet jedoch explizit mit einem mysqli_stmt-Objekt statt mit einer Verbindung.

Der Rückgabewert spiegelt die Anzahl der tatsächlich geänderten Zeilen wider. Bei UPDATE-Anweisungen zählt MySQL standardmäßig nur Zeilen, deren Werte sich wirklich verändert haben. Wurden alle passenden Zeilen zwar gefunden, aber nicht geändert, liefert die Funktion 0. Wird der MySQL-Flag CLIENT_FOUND_ROWS gesetzt, werden stattdessen die abgeglichenen (gefundenen) Zeilen gezählt.

Ein Rückgabewert von -1 zeigt an, dass das Statement einen Fehler verursacht hat. Ist die Anzahl der betroffenen Zeilen größer als den maximalen Wert eines PHP-ints, wird der Wert als string zurückgegeben, um Präzisionsverluste zu vermeiden.

Die Funktion ist besonders nützlich, um nach Schreiboperationen zu prüfen, ob tatsächlich Datensätze verändert wurden, z. B. um dem Benutzer eine aussagekräftige Rückmeldung zu geben oder um logische Fehler (wie fehlgeschlagene Updates wegen falscher WHERE-Bedingung) frühzeitig zu erkennen.

Parameter

Name	Typ	Default	Beschreibung
$statement Pflicht	mysqli_stmt		Ein `mysqli_stmt`-Objekt, das zuvor mit `mysqli_prepare()` erstellt und mit `mysqli_stmt_execute()` ausgeführt wurde.

Rückgabewert

Typ

int|string

Beschreibung

Gibt die Anzahl der betroffenen Zeilen als int zurück. Ist die Anzahl zu groß für einen Integer, wird ein string zurückgegeben. Der Wert -1 signalisiert einen Fehler beim Ausführen des Statements.

Beispiele

Datensatz aktualisieren und betroffene Zeilen prüfen

<?php
$mysqli = new mysqli('localhost', 'user', 'password', 'testdb');

if ($mysqli->connect_errno) {
    die('Verbindung fehlgeschlagen: ' . $mysqli->connect_error);
}

$stmt = $mysqli->prepare('UPDATE produkte SET preis = ? WHERE kategorie = ?');
$preis = 19.99;
$kategorie = 'Elektronik';
$stmt->bind_param('ds', $preis, $kategorie);
$stmt->execute();

$betroffene = mysqli_stmt_affected_rows($stmt);

if ($betroffene > 0) {
    echo "$betroffene Datensatz/Datensätze aktualisiert.";
} elseif ($betroffene === 0) {
    echo 'Keine Datensätze verändert (Werte bereits identisch oder keine passenden Zeilen).';
} else {
    echo 'Fehler beim Ausführen des Statements.';
}

$stmt->close();
$mysqli->close();

3 Datensatz/Datensätze aktualisiert.

Mehrere Datensätze löschen und Ergebnis auswerten

<?php
$mysqli = new mysqli('localhost', 'user', 'password', 'testdb');

$stmt = $mysqli->prepare('DELETE FROM bestellungen WHERE status = ? AND erstellt_am &lt; ?');
$status = 'storniert';
$datum  = '2023-01-01';
$stmt->bind_param('ss', $status, $datum);
$stmt->execute();

$geloescht = mysqli_stmt_affected_rows($stmt);
echo "Gelöschte Bestellungen: $geloescht";

$stmt->close();
$mysqli->close();

Gelöschte Bestellungen: 12

// Wichtig · Fallstricke

Wichtig: Die Funktion gibt erst nach dem Aufruf von mysqli_stmt_execute() einen aussagekräftigen Wert zurück. Wird sie vorher aufgerufen, ist das Ergebnis undefiniert.

Bei SELECT-Anweisungen sollte stattdessen mysqli_stmt_num_rows() verwendet werden, da mysqli_stmt_affected_rows() für lesende Abfragen nicht ausgelegt ist.

Wenn der MySQL-Client mit der Option CLIENT_FOUND_ROWS verbunden wird, zählt UPDATE gefundene (abgeglichene) statt tatsächlich geänderter Zeilen — dies kann zu unerwarteten Werten führen, wenn man nur auf Änderungen prüfen möchte.

Siehe auch

mysqli_affected_rows mysqli_stmt_execute mysqli_stmt_num_rows mysqli_prepare mysqli_stmt_close