Installiere die PHP-Treiber für SQL Server unter Windows

Verwenden Sie diesen Artikel, um die SQLSRV- und PDO_SQLSRV-Treiber für PHP auf Windows zu installieren. Die Treiber sind PHP-Erweiterungen, die den Microsoft ODBC-Treiber für SQL Server verwenden.

Bevor du anfängst, solltest du bestätigen, dass deine PHP-Version, Architektur und der Thread-Sicherheitsmodus in der Support-Matrix unterstützt werden. Der von einem Kommandozeilenprozess verwendete PHP-Laufzeitprozess und die von einem Webserver verwendete Laufzeit können unterschiedliche php.ini-Dateien verwenden. Konfigurieren und überprüfen Sie jede Laufzeit einzeln.

Am Ende des Verfahrens sollten sowohl sqlsrv_connect() als auch der PDO-Treiber sqlsrv für die vorgesehene CLI- oder Webanwendung verfügbar sein, und jede API sollte eine Testanfrage durchführen. Eine erfolgreiche Dateikopie allein ist keine abgeschlossene Installation.

Auswählen einer Installationsmethode

Method Verwenden Sie ihn, wenn Was es installiert
PHP-Installer für Erweiterungen (PIE) Du möchtest, dass der Installer den Treiber-Build für das PHP-Executable auswählt Ohne Versionsangabe php_sqlsrv.dll und php_pdo_sqlsrv.dll, mit versuchter automatischer Konfiguration
Veröffentlichte ZIP-Datei Du musst exakt vorgefertigte Dateien selbst auswählen, inspizieren oder bereitstellen Versionierte DLLs, ausgewählt durch PHP-Nebenversion, Thread-Sicherheitsmodus und Architektur

Verwenden Sie für beide Erweiterungen eine Methode. Halte die PIE- und ZIP-Konfigurationseinträge nicht gleichzeitig aktiv.

Installieren der erforderlichen Komponenten

  1. Installiere einen unterstützten PHP-Build von der PHP for Windows-Website. Füge das PHP-Verzeichnis PATH hinzu.

  2. Installiere das Visual C++ Redistributable, das von deinem PHP-Build benötigt wird. Stimmen Sie die x64- oder x86-Architektur mit PHP ab, wie in den PHP-für-Windows-Anforderungen beschrieben.

  3. Installieren Sie den neuesten Microsoft ODBC-Treiber für SQL Server.

  4. Führen Sie die folgenden Befehle aus, um die PHP-Laufzeit und die Konfigurationsdatei zu überprüfen:

    php --version
php --ini

    Wenn die geladene Konfigurationsdatei(none) ist, php.ini-development in das PHP-Verzeichnis nach php.ini kopieren.

  5. In php.ini, setzen Sie das Erweiterungsverzeichnis und aktivieren Sie die vom PHP Installer for Extensions (PIE) benötigten Erweiterungen:

    extension_dir = "ext"
extension=openssl
extension=zip

  6. Bestätigen Sie, dass PHP die erforderlichen Erweiterungen finden kann:

    php --ri openssl
php --ri zip

    Erfüllen Sie diese Voraussetzungen, bevor Sie PIE herunterladen.

Mit PIE installieren

PIE installiert die passende vorkompilierte Erweiterung für die PHP-Laufzeit. Unter Windows ist kein C-Compiler erforderlich.

  1. Wechsle in ein Verzeichnis, in das du schreiben kannst, und lade das neueste PIE PHP-Archiv (PHAR) herunter:

    curl.exe -fL --output pie.phar https://github.com/php/pie/releases/latest/download/pie.phar

    Die übrigen PIE-Befehle bezeichnen die Datei als .\pie.phar, also führen Sie diese Befehle in diesem Verzeichnis aus.

    Bevor Sie das PHAR ausführen, überprüfen Sie es mit der GitHub-Kommandozeilenschnittstelle (CLI):

    gh attestation verify --owner php .\pie.phar

    Bestätigen Sie den Download, bevor Sie weitermachen:

    dir pie.phar
php .\pie.phar --version

  2. Installieren Sie jeden Treiber einzeln:

    php .\pie.phar install microsoft/sqlsrv
php .\pie.phar install microsoft/pdo_sqlsrv

  3. Überprüfen Sie die Kommandozeilen-Laufzeitumgebung:

    php --ri sqlsrv
php --ri pdo_sqlsrv
php -m | findstr /I "sqlsrv pdo_sqlsrv"

PIE versucht, die Erweiterungen in der vom Befehlszeilenprogramm verwendeten Konfiguration zu aktivieren. Wenn PIE meldet, dass es eine Erweiterung nicht aktivieren konnte, fügen Sie die PIE-spezifischen Erweiterungseinträge hinzu.

Wenn dein Webserver eine andere PHP-Installation verwendet, installiere beide Treiber für die PHP-Version, die Architektur und den Thread-Sicherheitsmodus dieser Installation, bevor du ihn konfigurierst. Wenn dieselbe PHP-Installation einen anderen php.ini für den Webserver verwendet, aktiviere die installierten Treiber in dieser Datei. Überprüfen Sie die Web-Runtime separat und starten Sie den Webserver nach einer Änderung der Konfiguration neu.

PIE ändert die ausgewählte PHP-Installation. Es konfiguriert kein IIS, wählt keine IIS-Website aus und startet auch keine bestehenden PHP-Prozesse neu.

Installieren Sie manuell ein veröffentlichtes ZIP-Paket

Verwende diese Methode, wenn du die Treiberdateien selbst auswählen musst oder wenn PIE nicht geeignet ist.

  1. Laden Sie die Windows-ZIP für die veröffentlichte Treiberversion von der Microsoft Drivers for PHP for SQL Server Releases-Seite herunter.

  2. Führe php -i | findstr /I "PHP Version Thread Safety Architecture extension_dir" aus und notiere die PHP-Version, den Thread-Sicherheitsmodus, die Architektur und das Erweiterungsverzeichnis.

  3. Aus der ZIP kopieren Sie beide passenden Dynamic-Link-Bibliotheken (DLLs) in das Erweiterungsverzeichnis:

    php_sqlsrv_<php-version>_<ts-or-nts>_<x86-or-x64>.dll
php_pdo_sqlsrv_<php-version>_<ts-or-nts>_<x86-or-x64>.dll

    Zum Beispiel verwendet ein PHP 8.5 x64 thread-sicheres Runtime php_sqlsrv_85_ts_x64.dll und php_pdo_sqlsrv_85_ts_x64.dll.

  4. Fügen Sie die passenden Erweiterungsnamen zu den von der Runtime verwendeten php.ini hinzu:

    extension=php_sqlsrv_85_ts_x64.dll
extension=php_pdo_sqlsrv_85_ts_x64.dll

    Ersetzen Sie 85, ts, und x64 durch die Werte für Ihre PHP-Laufzeit. Mische keine threadsicheren und nicht-threadsicheren Dateien, 32-Bit- und 64-Bit-Dateien oder Dateien, die für eine andere PHP-Minor-Version erstellt wurden.

  5. Verifiziere die Laufzeit mit php --ri sqlsrv, php --ri pdo_sqlsrv, und php -m. Für einen Webserver sollten Sie den Zugriff auf diagnostische Seiten einschränken , bevor Sie eine temporäre phpinfo() Seite erstellen. Überprüfe die Geladene Konfigurationsdatei und beide Treiberabschnitte und schließe dann die Seite.

Konfigurieren Sie einen Webserver

Für IIS konfigurieren Sie das vorgesehene php-cgi.exe als FastCGI-Anwendung, indem Sie die PHP IIS-Installationsanleitung befolgen. Bestätigen Sie, dass die FastCGI-Anwendung das gleiche PHP-Verzeichnis und dieselbe Architektur verwendet, die Sie auch für die Installation der Treiber verwendet haben.

Für jeden Windows-Webserver:

  1. Schränken Sie den Zugriff auf die Diagnoseseite ein, bevor Sie eine temporäre phpinfo() Seite erstellen. Identifizieren Sie die ausführbare PHP-Executable und aktive php.ini des Webservers.

  2. Stellen Sie sicher, dass beide Treiber für die Weblaufzeit installiert sind. Für eine separate PHP-Installation verwenden Sie PIE mit der PHP-Programmdatei dieser Installation oder kopieren Sie beide passenden DLLs aus der veröffentlichten ZIP in das Erweiterungsverzeichnis. Füge die Treibereinträge zur Konfiguration der Weblaufzeit hinzu, auch wenn sich nur ihr php.ini von der CLI unterscheidet.

  3. Starten Sie den Webserver oder die FastCGI-Prozesse neu.

  4. Bestätigen Sie, dass die Seite separate Abschnitte sqlsrv und pdo_sqlsrv enthält.

  5. Entfernen Sie die phpinfo() Seite.

Teste beide PHP-APIs

Speichere dieses Programm als verify-php-drivers.php:

<?php
$failures = [];

if (!extension_loaded('sqlsrv') || !function_exists('sqlsrv_connect')) {
    $failures[] = 'SQLSRV is not available.';
}

if (!extension_loaded('pdo_sqlsrv') || !in_array('sqlsrv', PDO::getAvailableDrivers(), true)) {
    $failures[] = 'PDO_SQLSRV is not available.';
}

echo $failures === []
    ? "SQLSRV and PDO_SQLSRV are available." . PHP_EOL
    : implode(PHP_EOL, $failures) . PHP_EOL;

exit($failures === [] ? 0 : 1);

Führe es zuerst über die Kommandozeile aus:

php verify-php-drivers.php

Erwartete Ausgabe:

SQLSRV and PDO_SQLSRV are available.

Wenn Sie eine Web Runtime überprüfen müssen, legen Sie die Datei vorübergehend in den Document-Root der Website und rufen Sie sie in einem Browser auf. Entfernen Sie es nach dem Testen. Dieses Programm überprüft die PHP-APIs, ohne Datenbankzugangsdaten zu benötigen oder offenzulegen.

Teste eine Datenbankverbindung

Das Laden der Erweiterung ist nur die erste Installationskontrolle. Testen Sie beide APIs gegen das Datenbankziel, das die Anwendung verwendet, sodass der Test auch den ODBC-Treiber, den Netzwerkpfad, die Verschlüsselung, die Authentifizierung, die Abfrageausführung, die zurückgegebenen Werte und die Bereinigung abdeckt.

Setze temporäre Umgebungsvariablen in PowerShell, indem du Prompts beantwortest. Geben Sie die Server- und Datenbanknamen als Rohwerte ein, ohne Anführungszeichen oder Treibercodierung. Verwenden Sie den Zugangsdaten-Dialog oder die Eingabeaufforderung für ein Testkonto, das sich mit der Datenbank verbinden kann. Fügen Sie keine Zugangsdaten in eine Kommandozeile oder eine mitgeschnittene Terminalsitzung ein:

$env:SQL_SERVER_NAME = Read-Host "Server name (tcp:<server>,1433)"
$env:SQL_DATABASE = Read-Host "Database name"
$credential = Get-Credential -Message "Enter the database test account"
if ($null -eq $credential) {
    throw "Database test credentials are required."
}
$env:SQL_UID = $credential.UserName
$env:SQL_PWD = $credential.GetNetworkCredential().Password
Remove-Variable credential

Die Anmeldeaufforderung verdeckt das Passwort. Die Umgebung enthält das Klartext-Passwort, sodass PHP es lesen kann. Verwenden Sie diese Variablen nur in der Testsitzung, drucken Sie sie nicht aus und löschen Sie sie nach dem Test.

Speichere dieses Programm als test-php-drivers.php. Halte die Umgebungswerte unverändert. Das Programm verdoppelt schließende geschweifte Klammern und fügt äußere Klammern hinzu, bevor es den Datenbanknamen, den Benutzernamen und das Passwort an den Treiber übergibt. Diese Kodierung bewahrt wörtliche Klammern und verhindert, dass Semikolons die Verbindungsoptionen trennen.

<?php
$serverName = getenv('SQL_SERVER_NAME');
$database = getenv('SQL_DATABASE');
$uid = getenv('SQL_UID');
$pwd = getenv('SQL_PWD');

if ($serverName === false || $serverName === ''
    || $database === false || $database === ''
    || $uid === false || $uid === ''
    || $pwd === false || $pwd === '') {
    fwrite(STDERR, "Set SQL_SERVER_NAME, SQL_DATABASE, SQL_UID, and SQL_PWD." . PHP_EOL);
    exit(1);
}

$database = '{' . str_replace('}', '}}', $database) . '}';
$uid = '{' . str_replace('}', '}}', $uid) . '}';
$pwd = '{' . str_replace('}', '}}', $pwd) . '}';

$connectionOptions = [
    "Database" => $database,
    "UID" => $uid,
    "PWD" => $pwd,
    "Encrypt" => 1,
    "TrustServerCertificate" => 0,
];

$sqlsrvConnection = sqlsrv_connect($serverName, $connectionOptions);
if ($sqlsrvConnection === false) {
    foreach (sqlsrv_errors() as $error) {
        fwrite(
            STDERR,
            "SQLSRV {$error['SQLSTATE']} ({$error['code']}): {$error['message']}" . PHP_EOL
        );
    }
    exit(1);
}

$sqlsrvStatement = sqlsrv_query($sqlsrvConnection, "SELECT 1 AS TEST_VALUE");
if ($sqlsrvStatement === false) {
    foreach (sqlsrv_errors() as $error) {
        fwrite(
            STDERR,
            "SQLSRV {$error['SQLSTATE']} ({$error['code']}): {$error['message']}" . PHP_EOL
        );
    }
    sqlsrv_close($sqlsrvConnection);
    exit(1);
}

$sqlsrvRow = sqlsrv_fetch_array($sqlsrvStatement, SQLSRV_FETCH_ASSOC);
if ($sqlsrvRow === false || $sqlsrvRow === null || (int) $sqlsrvRow['TEST_VALUE'] !== 1) {
    fwrite(STDERR, "SQLSRV returned an unexpected result." . PHP_EOL);
    sqlsrv_free_stmt($sqlsrvStatement);
    sqlsrv_close($sqlsrvConnection);
    exit(1);
}

echo "SQLSRV query: 1" . PHP_EOL;
sqlsrv_free_stmt($sqlsrvStatement);
sqlsrv_close($sqlsrvConnection);

$failed = false;
try {
    $pdoConnection = new PDO(
        "sqlsrv:server=$serverName;Database=$database;Encrypt=1;TrustServerCertificate=0",
        $uid,
        $pwd,
        [PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION]
    );
    $pdoStatement = $pdoConnection->query("SELECT 1 AS TEST_VALUE");
    $pdoRow = $pdoStatement->fetch(PDO::FETCH_ASSOC);
    if ($pdoRow === false || (int) $pdoRow['TEST_VALUE'] !== 1) {
        throw new RuntimeException("PDO_SQLSRV returned an unexpected result.");
    }

    echo "PDO_SQLSRV query: 1" . PHP_EOL;
} catch (Throwable $exception) {
    fwrite(STDERR, $exception->getMessage() . PHP_EOL);
    $failed = true;
} finally {
    unset($pdoStatement);
    unset($pdoConnection);
}

exit($failed ? 1 : 0);

Führe das Programm mit demselben PHP-Executable aus, das du verifiziert hast:

php test-php-drivers.php

Erwartete Ausgabe:

SQLSRV query: 1
PDO_SQLSRV query: 1

Wenn die Erweiterungsprüfung besteht, dieses Programm aber fehlschlägt, verwenden Sie den SQLSTATE und den nativen Fehler, um die besitzende Schicht zu identifizieren. Installieren Sie die PHP-Erweiterungen nicht wegen eines Netzwerk-, Zertifikats-, Authentifizierungs- oder Datenbankberechtigungsfehlers neu.

Entferne das Skript und die temporären Variablen nach dem Test:

Remove-Item .\verify-php-drivers.php, .\test-php-drivers.php
Remove-Item Env:\SQL_SERVER_NAME, Env:\SQL_DATABASE, Env:\SQL_UID, Env:\SQL_PWD

Troubleshooting

Symptom Was soll überprüft werden? Beheben
Could not open input file: .\pie.phar Aktuelles Verzeichnis und Download-Standort Gehen Sie zum Verzeichnis mit dem verifizierten PHAR zurück oder laden Sie es herunter und überprüfen Sie es erneut
Unable to load dynamic library extension_dir, genauer DLL-Name, PHP-Minor-Version, Architektur und Thread-Sicherheitsmodus Wählen Sie die passende DLL aus oder führen Sie PIE mit der vorgesehenen PHP-ausführbaren Datei erneut aus
The specified module could not be found Treiber-DLL-Abhängigkeiten Bestätigen Sie, dass die DLL-Erweiterung existiert, installieren Sie das passende Visual C++ Redistributable und inspizieren Sie eventuelle verbleibende fehlende DLL-Abhängigkeiten
Die CLI lädt beide Treiber, aber IIS nicht. Andere PHP-Ausführungsdatei oder php.ini Vergleichen Sie phpinfo() mit php --ini, konfigurieren Sie die IIS-Laufzeit und starten Sie FastCGI neu
Module "sqlsrv" is already loaded Sowohl PIE- als auch ZIP-Einträge oder wiederholte Einträge Behalte einen SQLSRV-Eintrag und einen PDO_SQLSRV-Eintrag
PDO meldet could not find driver PDO_SQLSRV Konfiguration Führe php --ri pdo_sqlsrv aus und prüfe PDO::getAvailableDrivers()
PIE meldet Erfolg, aber eine alte Version bleibt erhalten Versionisierte ZIP-Einträge sind weiterhin aktiv Ersetzen Sie alte Einträge durch die unversionierten DLL-Einträge von PIE und starten Sie jeden PHP-Prozess neu

Wenn beide Erweiterungen geladen sind, kann PHP ihre APIs aufrufen. Erfassen Sie SQLSRV-Fehler oder die PDO-Ausnahme, bevor Sie die Treiberdateien ändern. Netzwerk-, Authentifizierungs-, Verschlüsselungs-, Zertifikats- und Datenbankberechtigungsfehler werden durch die Neuinstallation der PHP-Erweiterung nicht behoben.

Verwandte Inhalte

  • Zuletzt aktualisiert um