sqlsrv_errors — Funktion · PHP-Referenz

Signatur

sqlsrv_errors(int $errorsOrWarnings = SQLSRV_ERR_ALL): array|null

Beschreibung

sqlsrv_errors() liefert ein Array mit detaillierten Fehler- und Warnungsinformationen, die bei der zuletzt ausgeführten SQLSRV-Funktion aufgetreten sind. Dies ist das primäre Diagnosewerkzeug des SQLSRV-Treibers (Microsoft SQL Server für PHP) und sollte nach jeder fehlgeschlagenen Operation aufgerufen werden, um die genaue Ursache zu ermitteln.

Der Rückgabewert ist ein zweidimensionales Array, wobei jedes Element ein assoziatives Array mit den Schlüsseln SQLSTATE, code und message enthält. Über den Parameter $errorsOrWarnings lässt sich steuern, ob nur Fehler (SQLSRV_ERR_ERRORS), nur Warnungen (SQLSRV_ERR_WARNINGS) oder beides (SQLSRV_ERR_ALL) zurückgegeben werden soll.

Typischerweise wird sqlsrv_errors() in Fehlerbehandlungsroutinen eingesetzt: nach einem fehlgeschlagenen sqlsrv_query()-, sqlsrv_execute()- oder Verbindungsaufbau-Aufruf. Die Funktion gibt null zurück, wenn keine Fehler oder Warnungen vorliegen, was eine einfache Prüfung mit if ermöglicht.

Es empfiehlt sich, die zurückgegebenen Fehlermeldungen niemals unbereinigt an den Endnutzer auszugeben, da sie interne Datenbankstrukturinformationen enthalten können, die für Angreifer nützlich sein könnten.

Parameter

Name	Typ	Default	Beschreibung
$errorsOrWarnings	int	SQLSRV_ERR_ALL	Bestimmt, welche Art von Meldungen zurückgegeben wird. Mögliche Werte: `SQLSRV_ERR_ALL` (Fehler und Warnungen), `SQLSRV_ERR_ERRORS` (nur Fehler), `SQLSRV_ERR_WARNINGS` (nur Warnungen).

Rückgabewert

Typ

array|null

Beschreibung

Gibt ein Array von assoziativen Arrays zurück. Jedes innere Array enthält die Schlüssel SQLSTATE (SQL-Statuscode als String), code (nativer Fehlercode als Integer) und message (menschenlesbare Fehlerbeschreibung als String). Gibt null zurück, wenn keine Fehler oder Warnungen vorhanden sind.

Beispiele

Fehlerbehandlung nach fehlgeschlagenem Query

<?php
$serverName = 'localhost';
$connectionInfo = [
    'Database' => 'TestDB',
    'UID'      => 'sa',
    'PWD'      => 'geheim'
];

$conn = sqlsrv_connect($serverName, $connectionInfo);

if ($conn === false) {
    echo "Verbindung fehlgeschlagen:\n";
    foreach (sqlsrv_errors() as $error) {
        echo "SQLSTATE: " . $error['SQLSTATE'] . "\n";
        echo "Code:     " . $error['code']    . "\n";
        echo "Meldung:  " . $error['message'] . "\n";
    }
    exit;
}

$sql = "SELECT * FROM nicht_vorhandene_tabelle";
$stmt = sqlsrv_query($conn, $sql);

if ($stmt === false) {
    echo "Abfrage fehlgeschlagen:\n";
    $errors = sqlsrv_errors(SQLSRV_ERR_ERRORS);
    if ($errors !== null) {
        foreach ($errors as $error) {
            echo "[" . $error['SQLSTATE'] . "] " . $error['message'] . "\n";
        }
    }
}

sqlsrv_close($conn);

Abfrage fehlgeschlagen: [42S02] Invalid object name 'nicht_vorhandene_tabelle'.

Nur Warnungen abrufen und protokollieren

<?php
$serverName = 'localhost';
$connectionInfo = ['Database' => 'TestDB', 'UID' => 'sa', 'PWD' => 'geheim'];
$conn = sqlsrv_connect($serverName, $connectionInfo);

$sql = "EXEC sp_procedure_mit_warnung";
$stmt = sqlsrv_query($conn, $sql);

// Nur Warnungen (keine Fehler) auswerten
$warnings = sqlsrv_errors(SQLSRV_ERR_WARNINGS);
if ($warnings !== null) {
    foreach ($warnings as $warning) {
        // Intern protokollieren, NICHT an den Browser ausgeben
        error_log(
            sprintf(
                'SQLSRV Warnung – SQLSTATE: %s, Code: %d, Meldung: %s',
                $warning['SQLSTATE'],
                $warning['code'],
                $warning['message']
            )
        );
    }
} else {
    echo "Keine Warnungen aufgetreten.\n";
}

sqlsrv_free_stmt($stmt);
sqlsrv_close($conn);

Keine Warnungen aufgetreten.

// Wichtig · Fallstricke

Sicherheitshinweis: Die Fehlermeldungen von sqlsrv_errors() können sensible Informationen wie Tabellennamen, Spaltennamen oder Datenbankpfade enthalten. Geben Sie diese Meldungen niemals direkt an Endnutzer aus. Verwenden Sie stattdessen error_log() oder ein Logging-Framework.

Fehlerverhalten: sqlsrv_errors() gibt immer die Fehler der zuletzt ausgeführten SQLSRV-Operation zurück. Nach einem neuen erfolgreichen Aufruf einer SQLSRV-Funktion werden die vorherigen Fehler überschrieben.

Warnungen als Fehler: Standardmäßig werden SQL Server-Warnungen (z. B. Zeilenanzahl-Meldungen) nicht als Fehler behandelt. Mit sqlsrv_configure('WarningsReturnAsErrors', 1) kann dieses Verhalten geändert werden.

Die Funktion gehört zur SQLSRV-Erweiterung (ext/sqlsrv), die von Microsoft für Windows und Linux bereitgestellt wird und separat installiert werden muss.

Siehe auch

sqlsrv_connect sqlsrv_query sqlsrv_execute sqlsrv_configure SQLSRV_ERR_ERRORS