Nainstalujte PHP ovladače pro SQL Server na Windows

Použijte tento článek k instalaci SQLSRV a PDO_SQLSRV ovladačů pro PHP na Windows. Ovladače jsou rozšíření PHP, která používají Microsoft ODBC Driver for SQL Server.

Než začnete, ověřte si, že vaše PHP verze, architektura a režim bezpečnosti vláken jsou podporovány v matici podpory. PHP runtime používaný procesem příkazového řádku a runtime používaný webovým serverem mohou používat různé soubory php.ini. Konfigurujte a ověřujte každý runtime zvlášť.

Na konci procedury by měly být oba ovladače sqlsrv_connect() i ovladač PDO sqlsrv dostupné pro příslušnou CLI nebo webovou aplikaci a každé API by mělo provést testovací dotaz. Úspěšná kopie souboru sama o sobě není dokončená instalace.

Volba metody instalace

Metoda Použijte ji, když Co se nainstaluje
PHP instalátor rozšíření (PIE) Chcete, aby instalátor vybral sestavení driveru pro spustitelný soubor PHP Nepřeverzované php_sqlsrv.dll a php_pdo_sqlsrv.dll, s pokusem o automatickou konfiguraci
balíček ZIP k vydání Musíte si sami vybrat, zkontrolovat nebo nasadit přesné předpřipravené soubory Verzované DLL vybrané podle vedlejší verze PHP, režimu bezpečnosti vláken a architektury

Použijte jednu metodu pro obě rozšíření. Nemějte aktivní položky konfigurace PIE a ZIP současně.

Nainstalujte požadované součásti

  1. Nainstalujte podporované sestavení PHP z webu PHP for Windows. Přidejte adresář s PHP do PATH.

  2. Nainstalujte Visual C++ Redistributable požadovaný vaší sestavou PHP. Slaďte jeho architekturu x64 nebo x86 s PHP, jak je popsáno v požadavcích PHP pro Windows.

  3. Nainstalujte nejnovější ovladač Microsoft ODBC pro SQL Server.

  4. Spusťte následující příkazy k ověření prostředí PHP a konfiguračního souboru:

    php --version
php --ini

    Pokud je Loaded Configuration File(none), zkopírujte php.ini-development do php.ini v adresáři PHP.

  5. V php.ini, nastavte adresář rozšíření a povolte rozšíření požadovaná instalátorem PHP pro rozšíření (PIE):

    extension_dir = "ext"
extension=openssl
extension=zip

  6. Ověřte, že PHP dokáže najít nezbytná rozšíření:

    php --ri openssl
php --ri zip

    Nejprve splňte tyto předpoklady před stažením PIE.

Instalovat pomocí PIE

PIE nainstaluje odpovídající předkompilovaný driver pro runtime PHP. Na Windows nevyžaduje C kompilátor.

  1. Přepněte do adresáře, do kterého máte oprávnění k zápisu, a stáhněte si nejnovější archiv PIE PHP (PHAR):

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

    Zbývající příkazy PIE označují soubor jako .\pie.phar, takže je spouštějte ze stejného adresáře.

    Než spustíte PHAR, ověřte si ho pomocí rozhraní příkazového řádku GitHubu (CLI):

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

    Před pokračováním potvrďte stažení:

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

  2. Nainstalujte každý ovladač zvlášť:

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

  3. Ověřte runtime příkazového řádku:

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

PIE se snaží povolit rozšíření v konfiguraci používané spustitelným souborem příkazového řádku. Pokud PIE hlásí, že rozšíření nebylo možné povolit, přidejte položky rozšíření specifické pro PIE.

Pokud váš webový server používá jinou PHP instalaci, nainstalujte oba ovladače pro verzi PHP, architekturu a režim bezpečnosti vláken této instalace před konfigurací. Pokud stejná instalace PHP používá jiný php.ini pro webový server, povolte v tomto souboru nainstalovaná rozšíření. Ověřte webový runtime zvlášť a po změně konfigurace restartujte webový server.

PIE mění vybranou instalaci PHP. Nekonfiguruje IIS, nevybírá web IIS ani nerestartuje stávající PHP procesy.

Ručně nainstalovat vydaný ZIP balíček

Tuto metodu použijte, když potřebujete sami vybrat soubory ovladačů nebo když PIE není vhodné.

  1. Stáhněte si Windows ZIP pro vydanou verzi ovladačů ze stránky Microsoft Drivers for PHP for SQL Server releases.

  2. Spusť php -i | findstr /I "PHP Version Thread Safety Architecture extension_dir" a zaznamenej verzi PHP, režim bezpečnosti vláken, architekturu a adresář rozšíření.

  3. Z ZIP zkopírujte obě odpovídající dynamické knihovny (DLL) do adresáře rozšíření:

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

    Například PHP 8.5 x64 thread-safe runtime používá php_sqlsrv_85_ts_x64.dll a php_pdo_sqlsrv_85_ts_x64.dll.

  4. Přidejte odpovídající názvy rozšíření k php.ini, které runtime používá:

    extension=php_sqlsrv_85_ts_x64.dll
extension=php_pdo_sqlsrv_85_ts_x64.dll

    Nahraďte 85, ts, a x64 hodnotami pro vaše PHP runtime. Nemíchejte thread-safe a non-thread-safe soubory, 32bitové a 64bitové soubory nebo soubory vytvořené pro jinou podverzi PHP.

  5. Ověřte čas běhu pomocí php --ri sqlsrv, php --ri pdo_sqlsrv, a php -m. U webového serveru omezte přístup k diagnostické stránce před vytvořením dočasné phpinfo() stránky. Ověřte načtený konfigurační soubor a obě sekce ovladačů, poté stránku odstraňte.

Nakonfigurujte webový server

Pro IIS nakonfigurujte příslušný modul php-cgi.exe jako aplikaci FastCGI podle pokynů k instalaci PHP pro IIS. Ověřte, že aplikace FastCGI používá stejný PHP adresář a architekturu, jakou jste použili k instalaci ovladačů.

Pro jakýkoli Windows webový server:

  1. Omezte přístup k diagnostické stránce před vytvořením dočasné phpinfo() stránky. Identifikujte spustitelný soubor PHP a aktivní php.ini webového serveru.

  2. Ujistěte se, že oba ovladače jsou nainstalovány pro webové runtime. Pro samostatnou instalaci PHP použijte PIE s PHP spustitelným souborem této instalace, nebo zkopírujte obě odpovídající DLL z vydaného ZIP do jeho adresáře rozšíření. Přidejte záznamy ovladačů do konfigurace webového runtime, včetně případů, když se od CLI liší pouze jeho php.ini.

  3. Restartujte webový server nebo procesy FastCGI.

  4. Ujistěte se, že stránka obsahuje samostatné sekce sqlsrv a pdo_sqlsrv.

  5. Odstranit stránku phpinfo().

Otestujte obě PHP API

Uložte tento 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);

Spusť to nejdřív z příkazového řádku:

php verify-php-drivers.php

Očekávaný výstup:

SQLSRV and PDO_SQLSRV are available.

Pokud potřebujete ověřit webový runtime, umístěte soubor dočasně do kořene dokumentu webu a otevřete jej v prohlížeči. Po testování ho vyjměte. Tento program ověřuje rozhraní PHP API, aniž by vyžadoval nebo zpřístupňoval databázové přihlašovací údaje.

Otestujte připojení k databázi

Načtení rozšíření je jen první kontrolou instalace. Obě API otestujte proti cílové databázi, kterou aplikace používá, takže test zahrnuje také ovladač ODBC, síťovou cestu, šifrování, autentizaci, provádění dotazů, vrácené hodnoty a čištění.

Nastavte dočasné proměnné prostředí v PowerShellu odpovídáním na výzvy. Zadejte název serveru a databáze jako surové hodnoty, bez uvozovek nebo kódování ovladačů. Použijte dialogové okno nebo výzvu k zadání přihlašovacích údajů pro testovací účet, který se může připojit k databázi. Nezahrňujte přihlašovací údaje do příkazové řádky ani zaznamenané terminálové relace:

$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

Výzva k přihlašovacím údajům maskuje heslo. Prostředí obsahuje heslo v otevřeném textu, aby ho PHP mohl číst. Tyto proměnné používejte pouze v testovací relaci, netiskněte je a po testování je vymažte.

Uložte tento program jako test-php-drivers.php. Ponechte hodnoty prostředí beze změny. Program zdvojí zavírací závorky a přidává vnější závorky před předáním názvu databáze, uživatelského jména a hesla ovladači. Toto kódování zachovává složené závorky a zabraňuje tomu, aby středníky oddělovaly možnosti připojení.

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

Spusť program se stejným PHP spustitelným souborem, který jsi ověřil:

php test-php-drivers.php

Očekávaný výstup:

SQLSRV query: 1
PDO_SQLSRV query: 1

Pokud kontrola rozšíření projde, ale tento program selže, použijte SQLSTATE a nativní chybu k identifikaci vlastnící vrstvy. Nepřeinstalujte PHP rozšíření kvůli chybě sítě, certifikátu, ověření nebo oprávnění k databázi.

Odstraňte skript a dočasné proměnné po testování:

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 Co zkontrolovat Opravit
Could not open input file: .\pie.phar Aktuální adresář a místo stahování Vraťte se do adresáře obsahujícího ověřený PHAR, nebo si ho stáhněte a ověřte znovu
Unable to load dynamic library extension_dir, přesný název DLL, minor verze PHP, architektura a režim bezpečnosti vláken Vyberte odpovídající DLL nebo znovu spusťte PIE s zamýšleným PHP spustitelným souborem
The specified module could not be found Závislosti DLL ovladače Ověřte, že soubor DLL rozšíření existuje, nainstalujte odpovídající Visual C++ Redistributable a zkontrolujte případnou zbývající chybějící závislost DLL
CLI načítá oba ovladače, ale IIS ne Jiný spustitelný soubor PHP nebo php.ini Porovnejte phpinfo() s php --ini, nakonfigurujte runtime IIS a restartujte FastCGI
Module "sqlsrv" is already loaded Jak PIE zápisy, tak i ZIP, nebo opakované zápisy Ponechte jeden záznam SQLSRV a jeden záznam PDO_SQLSRV
Sestavy PDO could not find driver Konfigurace PDO_SQLSRV Spusťte php --ri pdo_sqlsrv a zkontrolujte PDO::getAvailableDrivers()
PIE hlásí úspěch, ale stará verze zůstává Verzované ZIP záznamy jsou stále aktivní Nahraďte staré záznamy neverzovanými DLL záznamy PIE a restartujte všechny procesy PHP

Pokud se obě rozšíření načtou, PHP může volat jejich API. Zachyťte chyby SQLSRV nebo výjimku PDO před změnou ovladačových souborů. Chyby v síti, autentizaci, šifrování, certifikátech a oprávněních databáze nejsou opraveny přeinstalací rozšíření PHP.

Související obsah

  • Poslední aktualizace v