mysqli_stmt_num_rows — Funktion · PHP-Referenz

Signatur

mysqli_stmt_num_rows(mysqli_stmt $statement): int|string

Beschreibung

mysqli_stmt_num_rows() liefert die Anzahl der Datensätze, die ein ausgeführtes vorbereitetes Statement (mysqli_stmt) zurückgegeben hat. Die Funktion ist das prozedurale Äquivalent zur objektorientierten Eigenschaft mysqli_stmt::$num_rows.

Wichtig: Damit die Funktion einen korrekten Wert zurückgibt, müssen alle Ergebnisse zuvor mit mysqli_stmt_store_result() in den Pufferspeicher des Clients übertragen worden sein. Ohne diesen Aufruf ist das Ergebnis in der Regel 0, weil der Client noch keine vollständige Kenntnis über die Anzahl der Zeilen hat.

Ab PHP 8.1 kann die Funktion bei nicht gepufferten Ergebnismengen den Wert als string zurückgeben, um sehr große Zeilenzahlen abzubilden, die den maximalen int-Wertebereich überschreiten würden. In der Praxis wird in den meisten Fällen ein int zurückgegeben.

Die Funktion eignet sich gut, um vor der Verarbeitung zu prüfen, ob ein SELECT-Statement überhaupt Treffer geliefert hat, bevor mit mysqli_stmt_bind_result() und mysqli_stmt_fetch() über die Ergebnisse iteriert wird.

Parameter

Name	Typ	Default	Beschreibung
$statement Pflicht	mysqli_stmt		Ein vorbereitetes Statement-Objekt, das mit `mysqli_prepare()` erzeugt und anschließend ausgeführt wurde.

Rückgabewert

Typ

int|string

Beschreibung

Gibt die Anzahl der gepufferten Zeilen als int zurück. Bei sehr großen Ergebnismengen (ab PHP 8.1) kann der Wert auch als string zurückgegeben werden. Ohne vorherigen Aufruf von mysqli_stmt_store_result() ist der Rückgabewert 0.

Beispiele

Anzahl der Treffer prüfen und Ergebnisse ausgeben

<?php
$link = mysqli_connect('localhost', 'benutzer', 'passwort', 'testdb');

if (!$link) {
    die('Verbindung fehlgeschlagen: ' . mysqli_connect_error());
}

$stmt = mysqli_prepare($link, 'SELECT id, name FROM benutzer WHERE aktiv = ?');
mysqli_stmt_bind_param($stmt, 'i', $aktiv);

$aktiv = 1;
mysqli_stmt_execute($stmt);

// Ergebnis puffern, damit num_rows korrekt funktioniert
mysqli_stmt_store_result($stmt);

$anzahl = mysqli_stmt_num_rows($stmt);
echo "Gefundene aktive Benutzer: " . $anzahl . "\n";

if ($anzahl > 0) {
    mysqli_stmt_bind_result($stmt, $id, $name);
    while (mysqli_stmt_fetch($stmt)) {
        echo "ID: $id, Name: $name\n";
    }
}

mysqli_stmt_close($stmt);
mysqli_close($link);

Gefundene aktive Benutzer: 3 ID: 1, Name: Alice ID: 2, Name: Bob ID: 5, Name: Clara

Objektorientierte Verwendung mit num_rows-Eigenschaft

<?php
$mysqli = new mysqli('localhost', 'benutzer', 'passwort', 'testdb');

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

$stmt = $mysqli->prepare('SELECT id, email FROM kunden WHERE land = ?');
$stmt->bind_param('s', $land);

$land = 'DE';
$stmt->execute();
$stmt->store_result(); // Pflicht für korrekte num_rows

echo 'Anzahl Kunden aus DE: ' . $stmt->num_rows . "\n";

// Alternativ als Funktion:
echo 'Via Funktion: ' . mysqli_stmt_num_rows($stmt) . "\n";

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

Anzahl Kunden aus DE: 12 Via Funktion: 12

// Wichtig · Fallstricke

Wichtiger Hinweis: mysqli_stmt_num_rows() funktioniert nur korrekt nach einem Aufruf von mysqli_stmt_store_result(). Ohne diesen Pufferschritt wird 0 zurückgegeben, auch wenn das Statement Ergebnisse geliefert hat.

mysqli_stmt_store_result() lädt alle Ergebnisse in den Speicher des Clients, was bei sehr großen Ergebnismengen zu hohem Speicherverbrauch führen kann. In solchen Fällen sollte erwogen werden, direkt über die Ergebnisse zu iterieren, statt die Gesamtanzahl zu ermitteln.

Die Funktion ist ausschließlich für SELECT- (und ähnliche datensatzliefernde) Statements gedacht. Für INSERT, UPDATE oder DELETE liefert mysqli_stmt_affected_rows() die relevante Zeilenzahl.

Siehe auch

mysqli_stmt_store_result mysqli_stmt_affected_rows mysqli_stmt_execute mysqli_stmt_fetch mysqli_num_rows mysqli_stmt_bind_result