Zainstaluj sterowniki PHP dla SQL Server na Windows

Użyj tego artykułu, aby zainstalować SQLSRV i PDO_SQLSRV sterowniki do PHP na Windows. Sterowniki to rozszerzenia PHP wykorzystujące Microsoft ODBC Driver for SQL Server.

Zanim zaczniesz, upewnij się, że wersja PHP, architektura oraz tryb bezpieczeństwa wątków są obsługiwane w matrycy zgodności. Środowisko uruchomieniowe PHP używane przez proces wiersza poleceń oraz środowisko uruchomieniowe używane przez serwer WWW mogą używać różnych plików php.ini. Konfiguruj i weryfikuj każde środowisko uruchomienia osobno.

Na końcu procedury zarówno sqlsrv_connect(), jak i sterownik PDO sqlsrv powinny być dostępne dla zamierzonego interfejsu CLI lub aplikacji internetowej, a każde API powinno wykonać zapytanie testowe. Sama udana kopia pliku nie jest zakończoną instalacją.

Wybieranie metody instalacji

Używaj jednej metody dla obu rozszerzeń. Nie trzymaj aktywnych wpisów konfiguracji PIE i ZIP jednocześnie.

Instalowanie wymagań wstępnych

1. Zainstaluj wspieraną wersję PHP z witryny PHP for Windows. Dodaj katalog PHP do PATH.

2. Zainstaluj Visual C++ Redistributable wymagany przez twoją wersję PHP. Dopasuj jego architekturę x64 lub x86 do PHP, jak opisano w wymaganiach PHP for Windows.

3. Zainstaluj najnowszy sterownik Microsoft ODBC dla SQL Server.

4. Wykonaj następujące polecenia, aby potwierdzić środowisko uruchomieniowe PHP i plik konfiguracyjny:

   php --version
   php --ini
   

   Jeśli Załadowany plik konfiguracyjny ma wartość (none), skopiuj php.ini-development do php.ini w katalogu PHP.

5. W php.ini, ustaw katalog rozszerzeń i włącz rozszerzenia wymagane przez PHP Installer for Extensions (PIE):

   extension_dir = "ext"
   extension=openssl
   extension=zip
   

6. Sprawdź, czy PHP potrafi zlokalizować wymagane rozszerzenia:

   php --ri openssl
   php --ri zip
   

   Popraw te wymagania wstępne przed pobraniem PIE.

Zainstaluj przy użyciu PIE

PIE instaluje odpowiadający prekompilowany sterownik dla środowiska uruchomieniowego PHP. Nie wymaga kompilatora C na Windows.

1. Zmień katalog, do którego masz uprawnienia zapisu, i pobierz najnowsze archiwum PIE PHP (PHAR):

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

   Pozostałe polecenia PIE odwołują się do pliku jako .\pie.phar, więc uruchamiaj je z tego samego katalogu.

   Zanim uruchomisz PHAR, sprawdź go za pomocą interfejsu wiersza poleceń GitHub (CLI):

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

   Potwierdź pobranie przed kontynuacją:

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

2. Zainstaluj każdy sterownik osobno:

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

3. Sprawdź środowisko uruchomieniowe wiersza poleceń:

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

PIE próbuje włączyć rozszerzenia w konfiguracji używanej przez program wiersza poleceń. Jeśli PIE raportuje, że nie mogło włączyć rozszerzenia, dodaj wpisy rozszerzeń specyficzne dla PIE.

Jeśli Twój serwer WWW korzysta z innej instalacji PHP, zainstaluj oba sterowniki dla wersji PHP, architektury i trybu bezpieczeństwa wielowątkowego tej instalacji przed konfiguracją. Jeśli ta sama instalacja PHP używa innego php.ini dla serwera WWW, włącz zainstalowane rozszerzenia w tym pliku. Zweryfikuj środowisko uruchomieniowe web osobno i zrestartuj serwer web po zmianie jego konfiguracji.

PIE zmienia wybraną instalację PHP. Nie konfiguruje IIS, nie wybiera witryny IIS ani nie restartuje istniejących procesów PHP.

Ręcznie zainstaluj opublikowany pakiet ZIP

Używaj tej metody, gdy musisz samodzielnie wybrać pliki sterownika lub gdy PIE nie jest odpowiednie.

1. Pobierz plik ZIP dla systemu Windows dla wydanej wersji sterownika ze strony wydań Microsoft Drivers for PHP for SQL Server.

2. Uruchom php -i | findstr /I "PHP Version Thread Safety Architecture extension_dir" i zanotuj wersję PHP, tryb bezpieczeństwa wątków, architekturę oraz katalog rozszerzeń.

3. Z pliku ZIP skopiuj obie pasujące biblioteki DLL do katalogu rozszerzenia:

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

   Na przykład środowisko uruchomieniowe PHP 8.5 x64 bezpieczne dla wątków używa php_sqlsrv_85_ts_x64.dll i php_pdo_sqlsrv_85_ts_x64.dll.

4. Dodaj odpowiadające nazwy rozszerzeń do php.ini używanego przez środowisko uruchomieniowe:

   extension=php_sqlsrv_85_ts_x64.dll
   extension=php_pdo_sqlsrv_85_ts_x64.dll
   

   Zastąp 85, ts i x64 wartościami dla twojego środowiska wykonawczego PHP. Nie mieszaj plików bezpiecznych dla wątków i niebezpiecznych dla wątków, plików 32-bitowych i 64-bitowych ani plików stworzonych dla innej pomocniczej wersji PHP.

5. Zweryfikowaj czas działania z php --ri sqlsrv, php --ri pdo_sqlsrv, oraz php -m. Dla serwera WWW należy ograniczyć dostęp do strony diagnostycznej przed utworzeniem tymczasowej phpinfo() strony. Zweryfikuj załadowany plik konfiguracyjny oraz obie sekcje sterowników, a następnie usuń stronę.

Konfiguruj serwer WWW

Dla IIS skonfiguruj docelowe php-cgi.exe jako aplikację FastCGI, stosując się do wytycznych dotyczących instalacji PHP IIS. Sprawdź, czy aplikacja FastCGI używa tego samego katalogu i architektury PHP, których użyto do zainstalowania sterowników.

Dla dowolnego serwera WWW Windows:

1. Ogranicz dostęp do strony diagnostycznej przed utworzeniem tymczasowej phpinfo() strony. Zidentyfikuj wykonywalny plik PHP serwera WWW i aktywną konfigurację php.ini.

2. Upewnij się, że oba sterowniki są zainstalowane dla środowiska uruchomieniowego sieci Web. Dla osobnej instalacji PHP użyj PIE z plikiem wykonywalnym PHP tej instalacji lub skopiuj oba pasujące pliki DLL z wydanego ZIP-a do katalogu rozszerzeń tej instalacji. Dodaj wpisy sterowników do konfiguracji środowiska uruchomieniowego web, w tym wtedy, gdy tylko jego php.ini różni się od CLI.

3. Zrestartuj serwer WWW lub procesy FastCGI.

4. Upewnij się, że strona zawiera osobne sekcje sqlsrv i pdo_sqlsrv.

5. Usuń phpinfo() stronę.

Przetestuj oba API PHP

Zapisz ten program jako 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);

Najpierw uruchom go z linii poleceń:

php verify-php-drivers.php

Oczekiwane dane wyjściowe:

SQLSRV and PDO_SQLSRV are available.

Jeśli musisz zweryfikować środowisko uruchomieniowe sieci Web, tymczasowo umieść plik w katalogu głównym dokumentów witryny i otwórz go w przeglądarce. Usuń go po testach. Program ten weryfikuje interfejsy API PHP bez konieczności udostępniania lub ujawniania danych uwierzytelniających do bazy danych.

Przetestuj połączenie bazy danych

Ładowanie rozszerzenia to tylko pierwszym sprawdzeniem instalacji. Przetestuj oba interfejsy API względem docelowej bazy danych, której używa aplikacja, aby test obejmował także sterownik ODBC, ścieżkę sieciową, szyfrowanie, uwierzytelnianie, wykonywanie zapytań, zwracane wartości oraz czyszczenie.

Ustaw tymczasowe zmienne środowiskowe w PowerShell, odpowiadając na prompty. Wprowadź nazwę serwera i bazy danych jako surowe wartości, bez cudzysłowów czy kodowania sterowników. Użyj okna dialogowego lub monitu poświadczeń dla konta testowego, które może połączyć się z bazą danych. Nie umieszczaj danych uwierzytelniających w wierszu poleceń ani w nagranej sesji terminalowej:

$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

Monit o dane logowania maskuje hasło. Środowisko zawiera hasło w tekstie jawnym, aby PHP mógł je odczytać. Używaj tych zmiennych tylko podczas sesji testowej, nie drukuj ich i usuwaj po testach.

Zapisz ten program jako test-php-drivers.php. Zachowaj wartości środowiska bez zmian. Program podwaja zamykające się klamry i dodaje zewnętrzne klamry przed przekazaniem nazwy bazy danych, nazwy użytkownika i hasła do sterownika. To kodowanie zachowuje dosłowne nawiasy klamrowe i zapobiega rozdzielaniu opcji połączeń przez średniki.

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

Uruchom program z tym samym plikiem wykonywalnym PHP, który zweryfikowałeś:

php test-php-drivers.php

Oczekiwane dane wyjściowe:

SQLSRV query: 1
PDO_SQLSRV query: 1

Jeśli test rozszerzenia przejdzie, ale ten program zakończy się niepowodzeniem, użyj SQLSTATE i błędu natywnego do zidentyfikowania warstwy będącej właścicielem. Nie instaluj ponownie rozszerzeń PHP w przypadku błędu sieciowego, certyfikatu, uwierzytelniania lub uprawnień bazy danych.

Usuń skrypt i zmienne tymczasowe po testach:

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

Jeśli oba rozszerzenia się załadują, PHP może wywołać ich API. Przed zmianą plików sterowników uchwyć błędy SQLSRV lub wyjątek PDO. Błędy sieciowe, uwierzytelniania, szyfrowania, certyfikatów i uprawnień do bazy danych nie są naprawiane przez ponowną instalację rozszerzenia PHP.

Treści powiązane

• Wymagania systemowe dla sterowników Microsoft for PHP for SQL Server
• Ładowanie sterowników firmy Microsoft dla języka PHP dla programu SQL Server
• Zaktualizuj sterowniki PHP dla SQL Server