Signatur
Beschreibung
sqlsrv_configure() ermöglicht es, Konfigurationsparameter des Microsoft SQLSRV-Treibers für PHP dynamisch zur Laufzeit anzupassen. Damit lassen sich u. a. das Verhalten bei Fehlern und Warnungen sowie die Ausführlichkeit der Protokollierung steuern.
Typische Einstellungen sind WarningsReturnAsErrors (ob SQL-Warnungen als Fehler behandelt werden), LogSeverity (welche Ereignisschwere protokolliert wird) und LogSubsystems (welche Treiber-Subsysteme geloggt werden). Die Funktion wirkt sich global auf alle nachfolgenden SQLSRV-Operationen innerhalb des aktuellen PHP-Prozesses aus.
Besonders nützlich ist die Funktion in Entwicklungsumgebungen, wo eine ausführliche Protokollierung hilfreich ist, während in Produktionsumgebungen das Logging auf ein Minimum reduziert werden sollte, um Performance und Sicherheit zu gewährleisten. Außerdem kann damit kontrolliert werden, ob SQL-Warnungen (z. B. geänderte Zeilenzahl) als behandlungspflichtige Fehler gewertet werden.
Die verfügbaren Einstellungen und ihre Werte sind als Konstanten im SQLSRV-Treiber definiert, z. B. SQLSRV_LOG_SEVERITY_ALL, SQLSRV_LOG_SUBSYSTEM_ALL oder SQLSRV_LOG_SUBSYSTEM_CONN.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $setting Pflicht | string | Der Name der zu ändernden Konfigurationseinstellung. Gültige Werte sind z. B. 'WarningsReturnAsErrors', 'LogSeverity' und 'LogSubsystems'. |
|
| $value Pflicht | mixed | Der neue Wert für die Einstellung. Für LogSeverity und LogSubsystems werden SQLSRV-Konstanten wie SQLSRV_LOG_SEVERITY_ALL oder SQLSRV_LOG_SUBSYSTEM_CONN erwartet. Für WarningsReturnAsErrors wird ein boolescher Wert (true/false) übergeben. |
Rückgabewert
true zurück, wenn die Einstellung erfolgreich gesetzt wurde, andernfalls false (z. B. bei einem ungültigen Einstellungsnamen oder unzulässigem Wert).Beispiele
Warnungen als Fehler behandeln und vollständiges Logging aktivieren
<?php
// Alle SQL-Warnungen als Fehler behandeln
$result = sqlsrv_configure('WarningsReturnAsErrors', true);
if (!$result) {
die('Konfiguration konnte nicht gesetzt werden.');
}
// Alle Schweregrade protokollieren
sqlsrv_configure('LogSeverity', SQLSRV_LOG_SEVERITY_ALL);
// Alle Subsysteme protokollieren (Verbindung, Anweisungen, Fehler etc.)
sqlsrv_configure('LogSubsystems', SQLSRV_LOG_SUBSYSTEM_ALL);
echo 'SQLSRV-Treiber wurde für ausführliches Debugging konfiguriert.' . PHP_EOL;
Produktionskonfiguration: Logging minimieren, Warnungen nicht als Fehler werten
<?php
// In der Produktion: Warnungen NICHT als Fehler behandeln
sqlsrv_configure('WarningsReturnAsErrors', false);
// Nur echte Fehler protokollieren
sqlsrv_configure('LogSeverity', SQLSRV_LOG_SEVERITY_ERROR);
// Nur Fehler-Subsystem aktivieren
sqlsrv_configure('LogSubsystems', SQLSRV_LOG_SUBSYSTEM_ERROR);
$serverName = 'localhost';
$connectionInfo = [
'Database' => 'MeineDatenbank',
'UID' => 'benutzer',
'PWD' => 'geheim',
];
$conn = sqlsrv_connect($serverName, $connectionInfo);
if (!$conn) {
$errors = sqlsrv_errors();
foreach ($errors as $error) {
echo 'Fehler: ' . $error['message'] . PHP_EOL;
}
exit;
}
echo 'Verbindung erfolgreich hergestellt.' . PHP_EOL;
sqlsrv_close($conn);
// Wichtig · Fallstricke
Sicherheitshinweis: In Produktionsumgebungen sollte das Logging auf ein Minimum reduziert werden (SQLSRV_LOG_SEVERITY_ERROR), da ausführliche Log-Ausgaben (z. B. SQL-Statements, Verbindungsparameter) in Logdateien sensible Daten wie Zugangsdaten oder Tabellenstrukturen preisgeben können.
Warnungen vs. Fehler: Standardmäßig ist WarningsReturnAsErrors auf true gesetzt, was bedeutet, dass SQL-Warnungen als PHP-Fehler behandelt werden. In bestimmten Szenarien (z. B. bei PRINT-Anweisungen in Stored Procedures) kann es sinnvoll sein, diesen Wert auf false zu setzen, um unerwünschte Fehlerbehandlung zu vermeiden.
Gültigkeitsbereich: Die mit sqlsrv_configure() gesetzten Einstellungen gelten global für den gesamten PHP-Prozess. Sie sollten daher möglichst früh im Skript gesetzt werden, bevor Verbindungen aufgebaut oder Abfragen ausgeführt werden.
Diese Funktion ist Teil der SQLSRV-Erweiterung (ext/sqlsrv) und steht nur zur Verfügung, wenn diese installiert und aktiviert ist. Sie ist nicht mit der PDO_SQLSRV-Erweiterung zu verwechseln.