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

• Um eine PHP-Entwicklungsumgebung einzurichten und deine erste Abfrage auszuführen, beginne mit Schritt 1: Konfiguration der Entwicklungsumgebung, dann Schritt 2: Erstellung einer SQL-Datenbank und Schritt 3: Mach einen Proof of Concept mit SQL über PHP.
• Um den Treiber unter Linux oder macOS zu installieren, beginnen Sie mit dem Installationstutorial für Linux und macOS und laden Sie die Microsoft-Treiber für PHP für SQL Server herunter.
• Um mit kennwortloser Authentifizierung eine Verbindung mit Azure SQL herzustellen, beginnen Sie mit Herstellen einer Verbindung mit Microsoft Entra-Authentifizierung und Verbindungsoptionen.
• Um eine bestehende Anwendung robust gegenüber vorübergehenden Ausfällen zu machen, navigieren Sie zu Resilienz bei Leerlaufverbindungen und Schritt 4: Stellen Sie mit PHP eine resiliente Verbindung mit SQL her.
• Um zwischen SQLSRV und PDO_SQLSRV zu entscheiden, gehe zu Übersicht der Microsoft Treiber für PHP für SQL Server und zum Vergleich von Ausführungsfunktionen.
• Um ein Installations-, Verbindungs- oder Abfrageproblem zu diagnostizieren, gehen Sie zu Troubleshooting, Handling errors and warnings sowie Logging activity.
• Um eine bestehende App schneller zu machen, gehe zu Performance Tuning.

Produktionsbasisplan für Azure SQL

Verwenden Sie diesen Codeausschnitt als Ausgangspunkt für eine produktionsorientierte Azure SQL-Verbindung mit dem PDO_SQLSRV-Treiber. Es liest den Server und die Datenbank aus Umgebungsvariablen (zum Beispiel App-Einstellungen von Azure App Service), authentifiziert sich mit einer verwalteten Identität, aktiviert TLS (Transport Layer Security) mit Validierung des Serverzertifikats, legt ein Anmeldezeitlimit fest, das einen Failover bei einem Kaltstart abdeckt, und setzt ConnectRetryCount und ConnectRetryInterval für die Resilienz von Leerlaufverbindungen in SQL Server. Die Hilfsfunktionen connectWithRetry und queryWithRetry auf Anwendungsebene versehen sowohl den anfänglichen Verbindungsaufbau als auch jede Anweisung mit einem begrenzten exponentiellen Backoff und trennen transiente Verbindungsfehler (die eine neue Verbindung erfordern) von transienten Abfragefehlern (bei denen dieselbe Verbindung wiederverwendet wird).

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} fixiert den ODBC-18-Treiber. 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. Weitere Informationen finden Sie unter Für das Verbindungszeichenfolgen-Attribut „Authentication“ wurde ein ungültiger Wert angegeben.

• 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 queryWithRetry auf Anwendungsebene, das eine Anweisung wiederholt, die aufgrund eines vorübergehenden Fehlers wie einem Deadlock oder einem Abfrage-Timeout fehlschlägt. Die beiden ergänzen sich, also behalte beide. Stellen Sie sicher, dass LoginTimeout mindestens ConnectRetryCount * ConnectRetryInterval beträgt, damit der Idle-Reconnect-Pfad sein volles Budget erhält; im Beispiel werden 90 Sekunden verwendet, um 5 × 15 Sekunden für Wiederholungsversuche plus zusätzlichen Spielraum für die initiale Anmeldung bei einem kalten Failover abzudecken.

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

  ; 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 in Azure App Service oder Azure Container Instances. Verwenden Sie andernfalls ihre 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 innerhalb des DSN selbst ab. Verwenden Sie daher den Konstruktorslot. Durch die Übergabe von null als Benutzer (wie im Beispiel) wird die vom System zugewiesene verwaltete Identität des Azure-Hosts ausgewählt. Für SQLSRV (prozedural) übergib UID im Array der Verbindungsoptionen.

• Legen Sie MultiSubnetFailover=true fest, wenn Sie eine Verbindung mit einem Listener einer Failovergruppe, einem Listener einer Verfügbarkeitsgruppe oder einem Endpunkt einer Failoverclusterinstanz herstellen. Das Aktivieren dieser Einstellung verbessert die Verbindungsleistung sowohl für Listener von Verfügbarkeitsgruppen mit einem einzelnen Subnetz als auch für solche mit mehreren Subnetzen. Weitere Informationen finden Sie unter Unterstützung für Hochverfügbarkeit, Notfallwiederherstellung.

• Fügen Sie für die horizontale Leseskalierung oder ein lesbares sekundäres Replikat ApplicationIntent=ReadOnly zum Datenquellennamen (Data Source Name, DSN) hinzu.

• 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 identisch: Fangen Sie eine false-Rückgabe von sqlsrv_connect ab, überprüfen Sie sqlsrv_errors() auf SQLSTATE, und warten Sie, bevor Sie es erneut versuchen. Ein vollständiges Beispiel finden Sie unter Schritt 4: Mit PHP eine resiliente Verbindung mit SQL herstellen.

• Die Wiederholungshilfsprogramme lesen $e->errorInfo[1], geschützt durch isset(). PDOException::$errorInfo ist als ?array deklariert und hat standardmäßig den Wert null, sodass die defensive Prüfung auf einen Treibercode von 0 zurückfällt, wobei das SQLSTATE-Präfix 08 entscheidet, ob ein neuer Versuch unternommen 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.
• Verbindungsstabilität: Integrierte Wiederholungsversuche für Leerlaufverbindungen 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

Referenzinhalt

Verwandte Aufgaben

Zugehöriger Inhalt

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