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 du aus PHP-Skripten Daten in der Microsoft SQL Datenbank-Engine lesen und schreiben kannst. Die beiden Erweiterungen verwenden denselben Microsoft ODBC-Treiber für SQL Server, bieten jedoch unterschiedliche PHP-APIs und treiberspezifische Optionen:

• SQLSRV stellt eine prozedurale API (sqlsrv_*Funktionen) bereit, die auf SQL Server-Funktionen zugeschnitten ist.
• PDO_SQLSRV implementiert die PHP Data Objects (PDO) -Schnittstelle. Du kannst die PDO-Aufrufe im bestehenden Datenbankcode behalten, aber du solltest vor dem Wechsel der Datenbank die Abfragen und treiberspezifischen Einstellungen überprüfen.

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. Beide Treiber akzeptieren PHP-Streams als Eingabeparameter. SQLSRV unterstützt das Abrufen großer Binär- und Zeichenwerte als Streams. Geh nicht davon aus, dass PDO_SQLSRV dasselbe Output-Streaming-Verhalten hat.

Auswählen des Startpunkts

• Um Ihre Installation zu überprüfen und eine parametrisierte Abfrage mit SQLSRV oder PDO_SQLSRV durchzuführen, beginnen Sie mit Quickstart: Verbinden Sie sich und fragen Sie mit den Microsoft Treibern für PHP ab.
• 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 App widerstandsfähig gegen vorübergehende Ausfälle zu machen, wähle Idle-Verbindungsresilienz.
• 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

Dieses PDO_SQLSRV Beispiel liest Server und Datenbank aus Umgebungsvariablen und verbindet sich mit einer verwalteten Identität. Es erstellt einen Datenquellennamen (DSN) und ermöglicht Transport Layer Security (TLS) mit Zertifikatsvalidierung. Lesen Sie diese Werte aus der vertrauenswürdigen Anwendungskonfiguration, nicht aus den Webanforderungsparametern. Führe das Programm auf einem Host mit einem Managed-Identity-Endpunkt aus, nachdem der Identität Zugriff auf die Datenbank gewährt wurde.

Die Hilfsfunktionen unternehmen bis zu drei Versuche, die Nur-Lese-Abfrage zu verbinden oder auszuführen, wenn ein aufgelisteter Fehler auftritt. Sie warten länger zwischen den Versuchen, ein Wiederholungsmuster, das als exponential backoff bezeichnet wird. Wenn ein Abfragefehler eine neue Verbindung erfordert, wirft der Abfragehelfer die Ausnahme, damit der aufrufende Code sie behandeln kann.

Verwenden Sie eine unterstützte PHP-Version, die PDO_SQLSRV-Erweiterung und Microsoft ODBC Driver 18 für SQL Server. Für unterstützte Authentifizierungswerte siehe Herstellen einer Verbindung mit Microsoft Entra-Authentifizierung. Verwenden Sie den Abfragehelfer nicht erneut für Schreib- oder Multistatement-Transaktionen, ohne eine anwendungsspezifische Wiederholungsrichtlinie zu entwerfen: Ein Fehler sagt Ihnen nicht immer, ob ein Schreiben committed wurde.

<?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];

// This read helper retries only the listed errors on the same connection.
// Other errors propagate; the caller must decide whether to reconnect.
const RETRYABLE_READ_ERROR_CODES = [1205, 1222, 40501, 10928, 10929];

/**
 * 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);
            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');
}

/**
 * Retry the standalone read-only query for errors that allow connection reuse.
 */
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, RETRYABLE_READ_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.');
}
$databaseValue = '{' . str_replace('}', '}}', $database) . '}';

$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,
    $databaseValue
);

$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 name FROM sys.databases WHERE database_id > ? ORDER BY name', [1]);
foreach ($stmt as $row) {
    echo $row['name'], PHP_EOL;
}

Verwenden Sie diese Einstellungen für Azure SQL-Datenbank Failover-Gruppen und Azure SQL Managed Instance.

• Driver={ODBC Driver 18 for SQL Server} wählt ODBC Driver 18 explizit aus, anstatt sich auf die Treiberentdeckung zu verlassen. Installiere es, bevor du das Beispiel ausführst.

• Setze SQL_DATABASE auf den tatsächlichen Datenbanknamen. Das Programm verdoppelt schließende geschweifte Klammern und umschließt den Namen mit geschweiften Klammern, bevor er in die DSN gesetzt wird. Das Escapen verhindert, dass spezielle Zeichen im Namen die Art und Weise ändern, wie der Treiber die Verbindungseinstellungen liest.

• ConnectRetryCount und ConnectRetryInterval die Widerstandsfähigkeit der ODBC-Leerlaufverbindungen zu steuern. Das Abfragetimeout der Anweisung begrenzt den Wiederherstellungsumfang während der Ausführung. Mit dem 30-sekündigen Abfrage-Timeout des Beispiels könnte ODBC stoppen, bevor alle fünf Wiederverbindungsversuche ausgeschöpft sind. LoginTimeout=90 steuert den Verbindungsaufbau, nicht das Wiederherstellungsbudget. Der Helper auf Anwendungsebene versucht ausgewählte Serverfehler erneut; er versucht keinen Abfrage-Timeout erneut und liefert teilweise abgerufene Ergebnisse nicht erneut zurück.

• Aktivieren Sie das Treiber-Logging bei den error_log()-Aufrufen des Programms. Für PDO_SQLSRV legen Sie pdo_sqlsrv.log_severity in php.ini fest oder zur Laufzeit mit ini_set(). Für SQLSRV konfigurieren LogSeverity Sie und LogSubsystems mit sqlsrv_configure(). 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. Verwenden Sie das Benutzernameargument des PDO Constructor, anstatt die Identität im DSN einzubetten. 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ür Read Scale-Out oder eine lesbare Sekundärversion fügen Sie dem DSN hinzu ApplicationIntent=ReadOnly .

• Nutzen Sie den von Ihrem SQL-Service bereitgestellten Endpunkt, einschließlich seiner cloud-spezifischen Domäne. Untersuchen Sie Zertifikatsnamensabweichungen, anstatt die Zertifikatsvalidierung zu deaktivieren. Verwenden Sie HostNameInCertificate nur, wenn Sie den erwarteten Zertifikatsnamen für diesen Endpunkt kennen.

• ODBC erwirbt Token für die Authentifizierung der verwalteten Identität und Service Principals. Mit AccessToken, erwirbt deine Anwendung das Token und gibt es an den Fahrer weiter; ODBC erschafft es nicht für dich. Weitere Informationen finden Sie unter Verwenden von Microsoft Entra ID mit dem ODBC-Treiber).

• Halte die Verbindungsinformationen außerhalb deines Codes. Speichere sie im Konfigurationssystem deiner Anwendung und nutze Azure Key Vault für geheime Schlüssel.

• Mit SQLSRV setzen Sie die Verbindungsoptionen im Array, das an sqlsrv_connect() übergeben wird. Überprüfe eine false Rückgabe und inspiziere sie in sqlsrv_errors(), bevor du entscheidest, ob du es erneut versuchen sollst. Setze Statement-Timeouts separat mit QueryTimeout. Resilienz bei Leerlaufverbindungen zeigt eine ODBC-Wiederverbindung, nicht eine Wiederholungsschleife auf Anwendungsebene.

• 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 PHP-APIs: SQLSRV stellt prozedurale Funktionen bereit. PDO_SQLSRV implementiert PDO. Installiere entweder eine Erweiterung oder beide.
• 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: Verwaltete Identität, Service Principal und extern erworbene Zugriffstoken über den zugrunde liegenden Microsoft ODBC-Treiber für SQL Server. Managed Identity ist passwortlos; ActiveDirectoryServicePrincipal verwendet ein Client-Secret.
• Always Encrypted: Verschlüssele sensible Spalten auf dem Client mit sicheren Enklaven für unterstützte Operationen auf verschlüsselten Daten.
• Verbindungsstabilität: Integrierte Wiederholungsversuche für Leerlaufverbindungen mit ConnectRetryCount und ConnectRetryInterval.
• PHP-Streams: Senden Sie große Binär- und Zeichenwerte aus Stream-Parametern mit beiden APIs. Verwenden Sie SQLSRV für den gestreamten Abruf.
• 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

Anfordern eines Features

Um eine Funktion anzufordern, öffne ein Problem in den Microsoft Treibern für PHP für SQL Server GitHub Repository.

Zugehöriger Inhalt

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