Telepítsd a SQL Server PHP illesztőprogramjait Windows-on

Használja ezt a cikket, hogy telepítse az SQLSRV és PDO_SQLSRV PHP illesztőprogramokat Windows rendszeren. A meghajtók PHP kiterjesztések, amelyek a Microsoft ODBC Driver for SQL Server-t használják.

Mielőtt elkezdenéd, győződj meg róla, hogy a PHP verziód, az architektúrád és a szálbiztonsági módod támogatott-e a támogatási mátrixban. A parancssori folyamat által használt PHP-futtatókörnyezet és a webszerver által használt futtatókörnyezet különböző php.ini fájlokat használhat. Minden futásidőt külön konfigurálj és ellenőrizz.

Az eljárás végén mind a sqlsrv_connect(), mind a PDO sqlsrv illesztőprogramnak elérhetőnek kell lennie a kívánt CLI-hez vagy webalkalmazáshoz, és mindegyik API-val sikeresen le kell futnia egy tesztlekérdezésnek. A sikeres fájlmásolás önmagában még nem jelenti a telepítés befejezését.

Telepítési módszer kiválasztása

Method Akkor használja, ha Mit telepít
PHP telepítő kiterjesztésekhez (PIE) Azt szeretnéd, hogy a telepítő kiválassza az illesztőprogram buildjét a PHP futtatható fájlhoz php_sqlsrv.dll és php_pdo_sqlsrv.dll verziószám nélküli, automatikus konfiguráció megkísérlésével
Kiadott ZIP csomag Neked kell kiválasztanod, ellenőrizned vagy telepítened a konkrét előre összeállított fájlokat A PHP alverziója, a szálbiztonsági mód és az architektúra alapján kiválasztott verziózott DLL-ek

Mindkét kiterjesztéshez használj egy módszert. Ne tartsd aktívan a PIE és ZIP konfigurációs bejegyzéseket egyszerre.

Előfeltételek telepítése

  1. Telepíts egy támogatott PHP buildet a PHP for Windows oldalról. Adja hozzá a PHP könyvtárat PATH.

  2. Telepítsd a PHP verzióhoz szükséges Visual C++ Redistributable-t. Egyeztesse annak x64 vagy x86 architektúráját a PHP-vel, ahogy azt a PHP for Windows követelményei leírják.

  3. Telepítsd a legújabb Microsoft ODBC Driver for SQL Server-t.

  4. Futtassa a következő parancsokat a PHP futtatókörnyezet és konfigurációs fájl megerősítéséhez:

    php --version
php --ini

    Ha a betöltött konfigurációs fájl a (none), másolja a php.ini-development fájlt a php.ini fájlba a PHP könyvtárban.

  5. A(z) php.ini részben állítsa be a bővítménykönyvtárat, és engedélyezze a PHP Installer for Extensions (PIE) által megkövetelt bővítményeket:

    extension_dir = "ext"
extension=openssl
extension=zip

  6. Ellenőrizze, hogy a PHP megtalálja az előfeltétel kiterjesztéseket:

    php --ri openssl
php --ri zip

    Teljesítsd ezeket az előfeltételeket, mielőtt letöltöd a PIE-t.

Telepítés PIE-vel

A PIE telepíti a megfelelő előre fordított illesztőprogramot a PHP futásidőhöz. Windows-on nem kell C fordító.

  1. Válts egy könyvtárba, ahová írhatsz, és töltsd le a legújabb PIE PHP archívumot (PHAR):

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

    A fennmaradó PIE parancsok .\pie.phar néven hivatkoznak a fájlra, ezért ugyanebből a könyvtárból futtasd le őket.

    Mielőtt futtatod a PHAR-t, ellenőrizd a GitHub parancssori felülettel (CLI):

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

    Erősítsd meg a letöltést, mielőtt folytatnád:

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

  2. Minden illesztőprogramot külön telepítsünk:

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

  3. Ellenőrizd a parancssori futtatókörnyezetet:

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

A PIE megpróbálja engedélyezni a parancssoros futtatható fájl által használt konfigurációban szereplő bővítményeket. Ha a PIE azt jelenti, hogy nem tudott engedélyezni egy bővítményt, add hozzá a PIE-specifikus bővítménybejegyzéseket.

Ha a webszervered más PHP-telepítést használ, telepítsd mindkét illesztőprogramot az adott telepítés PHP-verziójához, architektúrájához és szálbiztonsági módjához, mielőtt konfigurálnád. Ha ugyanaz a PHP-telepítés esetén a webszerverhez egy másik php.ini tartozik, engedélyezd a telepített illesztőprogramokat abban a fájlban. Külön ellenőrizd a webes futtatókörnyezetet, és újraindítsd a webszervert a konfiguráció megváltoztatása után.

A PIE megváltoztatja a kiválasztott PHP-telepítést. Nem konfigurálja az IIS-t, nem választ IIS-webhelyet, és nem indít újra meglévő PHP-folyamatokat.

Kiadott ZIP-csomag kézi telepítése

Használd ezt a módszert, amikor magadnak kell kiválasztanod a meghajtófájlokat, vagy ha a PIE nem megfelelő.

  1. Töltse le a kiadott illesztőprogram-verzióhoz tartozó Windows ZIP-et a Microsoft Drivers for PHP for SQL Server kiadások oldaláról.

  2. Futtasd php -i | findstr /I "PHP Version Thread Safety Architecture extension_dir" és rögzítsd a PHP verziót, a szálbiztonsági módot, az architektúrát és a bővítménykönyvtárat.

  3. A ZIP-ből másoljuk le mindkét megfelelő dinamikus link könyvtárat (DLL-eket) a bővítménykönyvtárba:

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

    Például egy PHP 8.5 x64 szálbiztos futtatókörnyezet a(z) php_sqlsrv_85_ts_x64.dll és php_pdo_sqlsrv_85_ts_x64.dll elemeket használ.

  4. Add hozzá a megfelelő bővítményneveket a futtatókörnyezet által használt php.ini-hoz:

    extension=php_sqlsrv_85_ts_x64.dll
extension=php_pdo_sqlsrv_85_ts_x64.dll

    Cseréld le a 85, ts és x64 elemeket a PHP futtatókörnyezeted értékeivel. Ne keverj szálbiztos és nem szálbiztos fájlokat, 32 és 64 bites fájlokat, vagy egy másik PHP alverzióhoz készült fájlokat.

  5. Ellenőrizd a futási időt php --ri sqlsrv, php --ri pdo_sqlsrv és php -m. Webszerver esetén korlátozza a diagnosztikai oldalhoz való hozzáférést, mielőtt ideiglenes phpinfo() oldalt hoz létre. Ellenőrizd a Loaded Configuration File-t és mindkét illesztőprogram-szakaszt, majd zárd be az oldalt.

Webszerver konfigurálása

IIS esetén a kívánt php-cgi.exe-t FastCGI alkalmazásként konfiguráljuk a PHP IIS telepítési útmutató követésével. Győződj meg róla, hogy a FastCGI alkalmazás ugyanazt a PHP könyvtárat és architektúrát használja, amit a driverek telepítéséhez használtál.

Bármely Windows webszerver esetén:

  1. Korlátozza a diagnosztikai oldalhoz való hozzáférést, mielőtt ideiglenes phpinfo() oldalt hozna létre. Azonosítsuk a webszerver PHP futtatható fájlját és aktív php.ini konfigurációját.

  2. Győződj meg róla, hogy mindkét illesztőprogram telepítve van a webes futásidőhöz. Külön PHP telepítéshez használd a PIE-t az adott telepítés PHP futtatható fájljával, vagy másolj mindkét egyező DLL-t a kiadott ZIP-ből annak kiterjesztési könyvtárába. Hozzáadjuk az illesztőprogrambejegyzéseket a webes futtatókörnyezet konfigurációjához, beleértve azt a helyzetet is, ha csak annak php.ini eltér a CLI-től.

  3. Indítsd újra a webszervert vagy a FastCGI folyamatokat.

  4. Ellenőrizd meg, hogy az oldal külön sqlsrv és pdo_sqlsrv szakaszokat tartalmaz.

  5. Távolítsd el az phpinfo() oldalt.

Teszteld mindkét PHP API-t

Mentse el ezt a programot így 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);

Először a parancssorból futtassa:

php verify-php-drivers.php

Várt kimenet:

SQLSRV and PDO_SQLSRV are available.

Ha webes futtatókörnyezetet kell ellenőrizned, ideiglenesen helyezd a fájlt a webhely dokumentumgyökerébe, és kérd le böngészőben. Teszt után távolítsd el. Ez a program ellenőrzi a PHP API-kat anélkül, hogy adatbázis-hitelesítő adatokat igényelne vagy felfedne.

Adatbázis-kapcsolat tesztelése

A bővítmény betöltése csak az első ellenőrzés a telepítés során. Mindkét API-t teszteljük az alkalmazás által használt adatbáziscél ellen, így a teszt lefedi az ODBC illezőprogramot, hálózati útvonalat, titkosítást, hitelesítést, lekérdezés végrehajtását, visszaadott értékeket és tisztítást is.

Állítson be ideiglenes környezeti változókat a PowerShellben a PowerShell-kérdésekre válaszolva. Adja meg a szerver- és adatbázisneveket nyers értékként, idézőjel vagy driver kódolás nélkül. Használd a hitelesítési párbeszédet vagy promptot egy olyan tesztfiókhoz, amely csatlakozni tud az adatbázishoz. Ne tegyél hitelesítő adatokat parancssorba vagy rögzített terminál-munkamenetbe:

$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

A hitelesítési párbeszédablak elrejti a jelszót. A környezet tartalmazza a tiszta szöveges jelszót, így a PHP el tudja olvasni. Ezeket a változókat csak a tesztelési munkamenetben használd, ne nyomtasd ki őket, és töröld őket a tesztelés után.

Mentsd el ezt a programot test-php-drivers.php. Tartsd változatlanul a környezeti értékeket. A program megduplázza a záró kapcsos zárójeleket, és hozzáadja a külső kapcsos zárójeleket, mielőtt átadja az adatbázis nevét, felhasználónevét és jelszavát az illesztőprogramnak. Ez a kódolás megőrzi a literális kapcsos zárójeleket, és megakadályozza, hogy a félvesszők elválasszák a csatlakozási lehetőségeket.

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

Futtasd a programot ugyanazzal a PHP futtatható fájllal, amit ellenőriztél:

php test-php-drivers.php

Várt kimenet:

SQLSRV query: 1
PDO_SQLSRV query: 1

Ha a bővítmény ellenőrzése átmegy, de ez a program nem fut le sikeresen, használd az SQLSTATE-et és a natív hibát a felelős réteg azonosítására. Ne telepítsd újra a PHP bővítményeket hálózati, tanúsítványhiba, hitelesítési vagy adatbázis-jogosultsági hiba esetén.

A szkriptet és az ideiglenes változókat tesztelés után távolítsd el:

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

Hibaelhárítás

Tünet Mit kell ellenőrizni? Kijavítás
Could not open input file: .\pie.phar Jelenlegi könyvtár és letöltési hely Térj vissza az ellenőrzött PHAR-t tartalmazó könyvtárba, vagy töltsd le és ellenőrizd újra
Unable to load dynamic library extension_dir, pontos DLL név, PHP kisebb verzió, architektúra és szálbiztonsági mód Válaszd ki a megfelelő DLL-t, vagy futtasd újra a PIE-t a kívánt PHP végrehajtható fájllal
The specified module could not be found Driver DLL függőségek Erősítsd meg, hogy létezik a kiterjesztési DLL, telepítsd a megfelelő Visual C++ Redistributable-t, és ellenőrizd a maradék hiányzó DLL függőséget
A CLI mindkét meghajtót betölti, de az IIS nem Különböző PHP futtatható fájl vagy php.ini Hasonlítsd össze a php --ini elemet a phpinfo() elemmel, konfiguráld az IIS-futtatókörnyezetet, és indítsd újra a FastCGI-t
Module "sqlsrv" is already loaded Mind a PIE-, mind a ZIP-bejegyzések, vagy ismétlődő bejegyzések Tartson meg egy SQLSRV bejegyzést és egy PDO_SQLSRV bejegyzést
PDO-jelentések could not find driver PDO_SQLSRV konfiguráció Futtasd php --ri pdo_sqlsrv és ellenőrizd PDO::getAvailableDrivers()
A PIE sikerről számol be, de egy régi verzió megmaradt Verziózott ZIP-bejegyzések továbbra is aktívak Cseréld le a régi bejegyzéseket a PIE verzió nélküli DLL bejegyzéseire, és indítsd újra minden PHP folyamatot

Ha mindkét bővítmény betöltődik, a PHP hívhatja az API-kat. Rögzítse az SQLSRV hibákat vagy a PDO kivételt a driver-fájlok megváltoztatása előtt. A hálózati, hitelesítési, titkosítási, tanúsítvány- és adatbázis-engedélyhibák nem oldhatók meg a PHP-bővítmény újratelepítésével.

Kapcsolódó tartalom

  • Utolsó frissítés időpontja: