Microsoft-Treiber für PHP für SQL Server

PHP-Treiber herunterladen

Die Microsoft-Treiber für PHP für SQL Server sind PHP-Erweiterungen, mit denen man Daten aus PHP-Skripten in der Microsoft SQL Datenbank-Engine lesen und schreiben kann. Das Paket enthält zwei Treiber, die denselben Microsoft ODBC-Treiber für SQL Server umfassen und dieselben Verbindungsoptionen teilen, sodass Sie die API auswählen können, die zu Ihrem Codebasis passt:

• SQLSRV stellt eine prozedurale API (sqlsrv_*Funktionen) bereit, die auf SQL Server-Funktionen zugeschnitten ist.
• PDO_SQLSRV implementiert die PHP Data Objects (PDO)-Schnittstelle, sodass Code, der bereits PDO für andere Datenbanken verwendet, SQL Server mit minimalen Änderungen ansprechen kann.

Beide Treiber verbinden sich mit der Azure SQL-Datenbank, der SQL-Datenbank in Microsoft Fabric, der Azure SQL Managed Instance und allen unterstützten Versionen und Editionen von SQL Server (einschließlich Express-Editionen). Sie verwenden PHP-Ströme, um große Binär- und Zeichenwerte zu verschieben, ohne sie vollständig in den Speicher zu laden.

Auswählen des Startpunkts

Schnellverbindung

Der folgende Ausschnitt ist die kürzeste End-to-End-Verbindung, die eine funktionierende PHP-Installation mit SQL Server oder Azure SQL ausführen kann. Nutze es, um zu bestätigen, dass dein Treiber, deine ODBC-Abhängigkeiten und der Netzwerkpfad verdrahtet sind, bevor du im nächsten Abschnitt zur Produktionsbasis übergehst.

<?php
$server   = getenv('SQL_SERVER')   ?: 'localhost';
$database = getenv('SQL_DATABASE') ?: 'master';
$user     = getenv('SQL_USER');
$password = getenv('SQL_PASSWORD');

$dsn = "sqlsrv:Driver={ODBC Driver 18 for SQL Server};Server=$server;Database=$database;Encrypt=true";
$pdo = new PDO($dsn, $user, $password, [
    PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION,
]);

foreach ($pdo->query('SELECT @@VERSION AS version') as $row) {
    echo $row['version'], PHP_EOL;
}

Für eine passwortlose Verbindung gegen Azure SQL fügen Sie (verwaltete Identität) oder einen anderen Wert zum DSN hinzu Authentication=ActiveDirectoryMsi und lassen Sie die Argumente $user/$password weg.Authentication Die folgende Produktionsbasis erweitert dasselbe Muster mit Wiederholungen, Auszeiten und Diagnosen.

Für einen lokalen SQL Server, der ein selbstsigniertes Zertifikat verwendet, Encrypt=true fehlschlägt die Validierung. Hinzufügen TrustServerCertificate=true nur für lokale Entwicklung. Siehe TLS-Zertifikatsfehler für die Produktionsalternativen.

Produktionsbasisplan für Azure SQL

Nutze diesen Ausschnitt als Ausgangspunkt für eine produktionsorientierte Azure SQL mit dem PDO_SQLSRV Treiber. Es liest Server und Datenbank aus Umgebungsvariablen (zum Beispiel Azure App Service-App-Einstellungen), authentifiziert sich mit einer verwalteten Identität, aktiviert Transport Layer Security (TLS) mit Serverzertifikatsvalidierung, setzt eine Login-Zeit, die einen Cold-Start-Failover abdeckt, und setzt ConnectRetryCount für ConnectRetryInterval die Widerstandsfähigkeit der SQL Server-Idle-Verbindung. Die Anwendungsebene connectWithRetry und queryWithRetry die Helfer umwickeln sowohl den initialen Connect als auch jede Anweisung mit einem begrenzten exponentiellen Backoff und trennen transienten Verbindungsfehler (die eine frische Verbindung erfordern) von transienten Abfragefehlern (die dieselbe Verbindung wiederverwenden).

Benötigt PHP 8.0 und neuere Versionen, die PDO_SQLSRV-Erweiterung und Microsoft ODBC-Treiber für SQL Server 17.3.1.1 und spätere Versionen für Authentication=ActiveDirectoryMsi. Für die vollständige Liste der unterstützten Werte Authentication siehe Verbinden mit Microsoft Entra-Authentifizierung.

<?php
declare(strict_types=1);

// Transient errors that require a fresh connection to recover. SQLSTATE values
// starting with '08' cover ODBC connection-established and connection-broken
// states (for example, 08001, 08S01).
const CONNECT_RETRY_SQLSTATE_PREFIX = '08';

// SQL Server error codes that are transient regardless of when they surface:
// 1205 (deadlock victim), 1222 (lock request timeout), and the Azure SQL
// throttling, mid-query failover, and "database not currently available"
// codes that arrive with SQLSTATE HY000.
const TRANSIENT_SERVER_ERROR_CODES = [1205, 1222, 40501, 40613, 40197, 10928, 10929, 49918];

/**
 * Open a connection, retrying transient failures with exponential backoff.
 */
function connectWithRetry(string $dsn, array $options, int $maxAttempts = 3): PDO
{
    for ($attempt = 1; $attempt <= $maxAttempts; $attempt++) {
        try {
            $pdo = new PDO($dsn, null, null, $options);
            error_log(sprintf('connected on attempt %d/%d', $attempt, $maxAttempts));
            return $pdo;
        } catch (PDOException $e) {
            $sqlstate = (string) $e->getCode();
            $driverCode = isset($e->errorInfo[1]) ? (int) $e->errorInfo[1] : 0;
            $isTransient = str_starts_with($sqlstate, CONNECT_RETRY_SQLSTATE_PREFIX)
                || in_array($driverCode, TRANSIENT_SERVER_ERROR_CODES, true);
            if (!$isTransient || $attempt === $maxAttempts) {
                error_log(sprintf('connect failed on attempt %d/%d: %s', $attempt, $maxAttempts, $e->getMessage()));
                throw $e;
            }
            $delay = 2 ** ($attempt - 1); // 1, 2, 4 seconds
            error_log(sprintf('connect attempt %d hit transient %s/%d; retrying in %d seconds', $attempt, $sqlstate, $driverCode, $delay));
            sleep($delay);
        }
    }
    throw new RuntimeException('connectWithRetry exhausted retries');
}

/**
 * Run a parameterized query, retrying transient statement failures on the same
 * connection. Deadlocks (1205) roll back the transaction before the driver sees
 * the error, so rerunning a single statement is safe. If the statement was part
 * of a multistatement transaction, wrap the whole transaction in your own retry
 * loop so earlier statements replay too.
 */
function queryWithRetry(PDO $pdo, string $sql, array $params = [], int $maxAttempts = 3): PDOStatement
{
    for ($attempt = 1; $attempt <= $maxAttempts; $attempt++) {
        try {
            $stmt = $pdo->prepare($sql);
            $stmt->execute($params);
            return $stmt;
        } catch (PDOException $e) {
            $driverCode = isset($e->errorInfo[1]) ? (int) $e->errorInfo[1] : 0;
            $isTransient = in_array($driverCode, TRANSIENT_SERVER_ERROR_CODES, true);
            if (!$isTransient || $attempt === $maxAttempts) {
                error_log(sprintf('query failed on attempt %d/%d: %s', $attempt, $maxAttempts, $e->getMessage()));
                throw $e;
            }
            $delay = 2 ** ($attempt - 1);
            error_log(sprintf('query attempt %d hit transient code %d; retrying in %d seconds', $attempt, $driverCode, $delay));
            sleep($delay);
        }
    }
    throw new RuntimeException('queryWithRetry exhausted retries');
}

// Load endpoint details from application configuration. In Azure App Service,
// these can come from app settings or Key Vault-backed settings.
$server = getenv('SQL_SERVER') ?: null;
$database = getenv('SQL_DATABASE') ?: null;

if ($server === null || $database === null) {
    throw new RuntimeException('Set SQL_SERVER and SQL_DATABASE in your application configuration.');
}

$dsn = sprintf(
    'sqlsrv:Driver={ODBC Driver 18 for SQL Server};Server=%s;Database=%s;'
    . 'Encrypt=true;TrustServerCertificate=false;'
    . 'LoginTimeout=90;Authentication=ActiveDirectoryMsi;'
    . 'ConnectRetryCount=5;ConnectRetryInterval=15;'
    . 'MultiSubnetFailover=true;',
    $server,
    $database
);

$options = [
    PDO::ATTR_ERRMODE               => PDO::ERRMODE_EXCEPTION,
    PDO::ATTR_DEFAULT_FETCH_MODE    => PDO::FETCH_ASSOC,
    PDO::ATTR_EMULATE_PREPARES      => false,
    PDO::SQLSRV_ATTR_QUERY_TIMEOUT  => 30,
];

$pdo = connectWithRetry($dsn, $options);
$stmt = queryWithRetry($pdo, 'SELECT TOP (?) name FROM sys.databases ORDER BY name', [5]);
foreach ($stmt as $row) {
    echo $row['name'], PHP_EOL;
}

Dieser Codeausschnitt ist für Azure SQL-Datenbank Failovergruppen und Azure SQL Managed Instance optimiert.

• Driver={ODBC Driver 18 for SQL Server} pinnt den ODBC 18 Driver. Wenn der Host auch ODBC 17 installiert hat, kann PDO_SQLSRV auf ODBC 17 binden. Ältere 17.x-Builds lehnen neuere Authentication Werte ab; zum Beispiel Authentication=ActiveDirectoryMsi benötigt ODBC 17.3.1.1 oder eine spätere Version. Siehe Invalid Value angegeben für das Verbindungszeichenfolge-Attribut 'Authentication'.

• ConnectRetryCountund ConnectRetryInterval sind ODBC-Verbindungszeichenfolge-Schlüsselwörter, die die Widerstandsfähigkeit der SQL Server Idle-Verbindung ermöglichen: Der Treiber stellt eine defekte Idle-Verbindung transparent wieder her. Das unterscheidet sich von der Anwendungsebene queryWithRetry, bei der eine Aussage , die mit einem vorübergehenden Fehler wie Deadlock oder Abfrage-Timeout scheitert, erneut versucht. Die beiden ergänzen sich, also behalte beide. Stellen Sie sicher, LoginTimeoutConnectRetryCount * ConnectRetryInterval dass zumindest der Idle-Reconnect-Pfad sein volles Budget erhält; die Probe benötigt 90 Sekunden, um 5 × 15 Sekunden Wiederholungen plus Headroom für die erste Anmeldung bei einem Cold Failover abzudecken.

• Ergänzen Sie die Aufrufe auf Anwendungsebene error_log() durch Diagnostik auf der Fahrerseite. Für PDO_SQLSRV setzen pdo_sqlsrv.log_severity Sie in php.ini (nur bei der Initialisierung einstellbar); für SQLSRV rufen Sie zur Laufzeit auf.sqlsrv_configure("LogSubsystems", ...) Weitere Informationen finden Sie unter Logging von Aktivitäten.

  ; php.ini - enable PDO_SQLSRV driver diagnostics alongside the application-level
  ; error_log() calls in the sample. Use 1 (errors) in production; -1 (all) is
  ; useful during triage but very chatty.
  [pdo_sqlsrv]
  pdo_sqlsrv.log_severity = 1
  

• Für eine vom Benutzer zugewiesene verwaltete Identität wird die ID der Identität als PDO-Argument $username (new PDO($dsn, $identityId, null, $options)) weitergegeben. Verwenden Sie die Client-ID der Identität auf Azure App Service oder Azure Container Instance; ansonsten verwenden Sie deren Objekt-ID. Die PHP-Treiber übernehmen dieses Verhalten vom zugrunde liegenden Microsoft ODBC Driver for SQL Server; für weitere Informationen siehe Verwendung von Microsoft Entra ID mit dem ODBC-Treiber. PDO_SQLSRV lehnt UID im DSN selbst ab, also nutze den Konstruktor-Slot. Das Geben null als Benutzer (wie im Beispiel) wählt die systemzugewiesene verwaltete Identität des Azure-Hosts aus. Für SQLSRV (prozedural) gib UID das Verbindungsoptions-Array ein.

• Setzen Sie ein, MultiSubnetFailover=true wenn Sie sich mit einem Failover-Group-Listener, einem Availability-Group-Listener oder einem Failover-Cluster-Instanzendpunkt verbinden. Das Setzen verbessert die Verbindungsleistung sowohl für Single-Subnet- als auch Multi-Subnet-Verfügbarkeitsgruppen-Listener. Weitere Informationen finden Sie unter Support for High Availability, Disaster Recovery.

• Für Read Scale-out oder ein lesbares sekundäres Dokument fügen Sie dem Data Source Name (DSN) hinzu ApplicationIntent=ReadOnly .

• Für souveräne Clouds, bei denen das Zertifikat Subject Alternative Name (SAN) den Host, mit dem du dich verbindest, nicht enthält, füge HostNameInCertificate es dem DSN hinzu (zum Beispiel *.database.usgovcloudapi.net bei Azure Government).

• Der Treiber basiert auf dem zugrunde liegenden Microsoft ODBC-Treiber für SQL Server zur Token-Erfassung. Managed Identity, Service Principal und Access Token Flows laufen alle über ODBC. Weitere Informationen finden Sie unter Verwenden von Microsoft Entra ID mit dem ODBC-Treiber).

• Für höhere Sicherheit und Portabilität zwischen verschiedenen Umgebungen sollten Sie die Verbindungsinformationen außerhalb Ihres Codes halten. Speichere Verbindungsinformationen im Konfigurationssystem deiner Anwendung und nutze Azure Key Vault für sensible Werte und zentral verwaltete Verbindungseinstellungen.

• Die entsprechende SQLSRV-Verbindung verwendet sqlsrv_connect($server, ['Database' => $database, 'Encrypt' => true, 'Authentication' => 'ActiveDirectoryMsi', /* ... */]) und gibt eine Ressource zurück. Das Wiederholungsmuster ist dasselbe: Fang eine false Rückgabe von sqlsrv_connect, inspektiere sqlsrv_errors() auf SQLSTATE und zieh dich zurück, bevor du es erneut versuchst. Ein ausgearbeitetes Beispiel finden Sie in Schritt 4: Verbinde dich resilient mit SQL mit PHP.

• Die Wiederversuchshelfer lesen $e->errorInfo[1] geschützt durch isset(). PDOException::$errorInfo als deklariert ?array und standardmäßig auf null, sodass die defensive Prüfung auf einen Treibercode von 0 zurückgreift und dem SQLSTATE-Präfix 08 erlaubt zu entscheiden, ob es erneut versucht wird.

Weitere Informationen zu den einzelnen Teilen dieser Konfiguration finden Sie unter:

• Verbindungsoptionen
• Herstellen einer Verbindung mit der Microsoft Entra-Authentifizierung
• Widerstandsfähigkeit der Leerlaufverbindung
• Herstellen einer Verbindung mit einer Microsoft Azure SQL-Datenbank
• Unterstützung für hohe Verfügbarkeit und Katastrophenwiederherstellung

Informationen zum Katalog der vorübergehenden Azure SQL-Fehler finden Sie unter Problembehandlung bei vorübergehenden Verbindungsfehlern.

Wichtigste Funktionen

• Zwei APIs, ein Treiberpaket: Procedural SQLSRV für SQL Server-First-Code oder PDO_SQLSRV für portablen PDO-Code.
• Breite Plattformunterstützung: Läuft auf Windows, Linux und macOS mit unterstützten PHP-Versionen.
• Verschlüsselte Verbindungen: TLS-verschlüsselte Verbindungen über Encrypt=true, wobei die Validierung von Serverzertifikaten durch kontrolliert wird TrustServerCertificate.
• Microsoft Entra ID-Authentifizierung: Passwortlose Verbindungen mit verwalteter Identität, Service Principal und Zugangstoken laufen über den zugrunde liegenden Microsoft ODBC-Treiber für SQL Server.
• Always Encrypted: clientseitige Verschlüsselung für vertrauliche Spalten mit optionalen sicheren Enklaven für Vorgänge direkt an Ort und Stelle.
• Verbindungsresilienz: Eingebaute Idle-Verbindungsproben mit ConnectRetryCount und ConnectRetryInterval.
• PHP-Streams: Lesen und schreiben Sie große Binär- und Zeichenwerte als Streams, anstatt sie in den Speicher zu laden.
• Unterstützung für Datentypen von Rich SQL Server: datetimeoffset, tabellenwertige Parameter, nvarchar und Unicode mit PDO::SQLSRV_ENCODING_UTF8.

Get started

Konfigurieren und Verbinden

Authenticate

Secure

Daten abrufen und aktualisieren

Datentypen

Fehler und Diagnose

Bereitstellen und Betreiben

Reference

Verwandte Aufgaben

Zugehöriger Inhalt

• Microsoft-Treiber für PHP für SQL Server auf GitHub
• Microsoft ODBC-Treiber für SQL Server
• SQL Server-Treiber