Installera PHP-drivrutinerna för SQL Server på Windows

Använd den här artikeln för att installera SQLSRV och PDO_SQLSRV drivrutiner för PHP på Windows. Drivrutinerna är PHP-tillägg som använder Microsoft ODBC-drivrutinen för SQL Server.

Innan du börjar, kontrollera att din PHP-version, arkitektur och trådsäkerhetsläge stöds i supportmatrisen. PHP-runtimen som används av en kommandoradsprocess och runtimen som används av en webbserver kan använda olika php.ini filer. Konfigurera och verifiera varje runtime separat.

I slutet av proceduren ska både sqlsrv_connect() och PDO-drivrutinen sqlsrv vara tillgängliga för den avsedda CLI:n eller webbapplikationen, och varje API ska slutföra en testfråga mot databasen. En lyckad filkopia i sig är inte en fullständig installation.

Välj en installationsmetod

Method Använd den när Vad den installerar
PHP-installationsprogram för tillägg (PIE) Du vill att installationsprogrammet ska välja drivrutinsversionen för den körbara PHP-filen Utan versionshantering php_sqlsrv.dll och php_pdo_sqlsrv.dll, med försök till automatisk konfiguration
Publicerat ZIP-paket Du måste själv välja, inspektera eller driftsätta exakt förbyggda filer Versionserade DLL:er valda efter PHP-minorversion, trådsäkerhetsläge och arkitektur

Använd en metod för båda tilläggen. Håll inte PIE- och ZIP-konfigurationsposter aktiva samtidigt.

Installera nödvändiga förutsättningar

  1. Installera en stödd PHP-build från PHP for Windows-sidan. Lägg till PHP-katalogen i PATH.

  2. Installera den Visual C++ Redistributable som krävs av din PHP-version. Anpassa dess x64- eller x86-arkitektur till PHP, som beskrivs i kraven för PHP för Windows.

  3. Installera den senaste Microsoft ODBC-drivrutinen för SQL Server.

  4. Kör följande kommandon för att kontrollera PHP-runtime och konfigurationsfilen:

    php --version
php --ini

    Om Loaded Configuration File är (none), kopiera php.ini-development till php.ini i PHP-katalogen.

  5. I php.ini-filen, ställ in tilläggskatalogen och aktivera de tillägg som krävs av PHP Installer for Extensions (PIE):

    extension_dir = "ext"
extension=openssl
extension=zip

  6. Bekräfta att PHP kan hitta de nödvändiga tilläggen:

    php --ri openssl
php --ri zip

    Åtgärda dessa förutsättningar innan du laddar ner PIE.

Installera med PIE

PIE installerar det matchande förkompilerade tillägget för PHP-runtime. Det kräver ingen C-kompilator på Windows.

  1. Byt till en katalog du har skrivbehörighet till, och ladda ner det senaste PIE PHP-arkivet (PHAR):

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

    De återstående PIE-kommandona hänvisar till filen som .\pie.phar, så kör dem från samma katalog.

    Innan du kör PHAR, verifiera det med GitHub:s kommandoradsgränssnitt (CLI):

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

    Bekräfta nedladdningen innan du fortsätter:

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

  2. Installera varje drivrutin separat:

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

  3. Verifiera kommandoradens körningsmiljö:

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

PIE försöker aktivera tilläggen i konfigurationen som används av kommandoradskörbaren. Om PIE rapporterar att de inte kunde aktivera ett tillägg, lägg till de PIE-specifika tilläggsposterna.

Om din webbserver använder en annan PHP-installation, installera båda tilläggen för den installationens PHP-version, arkitektur och trådsäkerhetsläge innan du konfigurerar den. Om samma PHP-installation använder en annan php.ini för webbservern, aktivera de installerade drivrutinerna i den filen. Verifiera webbkörningsmiljön separat och starta om webbservern efter att ha ändrat dess konfiguration.

PIE ändrar den valda PHP-installationen. Den konfigurerar inte IIS, väljer inte en IIS-webbplats eller startar om befintliga PHP-processer.

Installera manuellt ett utgivet ZIP-paket

Använd denna metod när du behöver välja drivrutinsfilerna själv eller när PIE inte är lämpligt.

  1. Ladda ner Windows ZIP för den släppta drivrutinsversionen från sidan Microsoft Drivers for PHP for SQL Server releases.

  2. Kör php -i | findstr /I "PHP Version Thread Safety Architecture extension_dir" och notera PHP-versionen, trådsäkerhetsläget, arkitekturen och tilläggskatalogen.

  3. Från ZIP-filen, kopiera båda matchande dynamiska länkbibliotek (DLL) till tilläggskatalogen:

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

    Till exempel använder en PHP 8.5 x64 trådsäker runtime php_sqlsrv_85_ts_x64.dll och php_pdo_sqlsrv_85_ts_x64.dll.

  4. Lägg till matchande tilläggsnamn till det php.ini som används av runtime:

    extension=php_sqlsrv_85_ts_x64.dll
extension=php_pdo_sqlsrv_85_ts_x64.dll

    Ersätt 85, ts, och x64 med värdena för din PHP-runtime. Blanda inte trådsäkra och icke-trådsäkra filer, 32-bitars och 64-bitarsfiler, eller filer som är byggda för en annan PHP-minorversion.

  5. Verifiera körtiden med php --ri sqlsrv, php --ri pdo_sqlsrv, och php -m. För en webbserver, begränsa åtkomsten till diagnostiska sidor innan du skapar en tillfällig phpinfo() sida. Kontrollera den laddade konfigurationsfilen och båda drivrutinssektionerna, ta sedan bort sidan.

Konfigurera en webbserver

För IIS, konfigurera den avsedda php-cgi.exe-komponenten som ett FastCGI-program genom att följa installationsanvisningarna för PHP på IIS. Bekräfta att FastCGI-applikationen använder samma PHP-katalog och arkitektur som du använde för att installera drivrutinerna.

För alla Windows-webbservrar:

  1. Begränsa åtkomsten till den diagnostiska sidan innan du skapar en tillfällig phpinfo() sida. Identifiera webbserverns PHP-exekverbara fil och den aktiva php.ini.

  2. Se till att båda drivrutinerna är installerade för webbkörmiljön. För en separat PHP-installation, använd PIE med den installationens PHP-exekverbara fil, eller kopiera båda matchande DLL-filerna från den släppta ZIP-filen till dess tilläggskatalog. Lägg till drivrutinsposterna i webbruntimens konfiguration, även när endast dess php.ini skiljer sig från CLI:ns.

  3. Starta om webbservern eller FastCGI-processerna.

  4. Bekräfta att sidan innehåller separata sqlsrv- och pdo_sqlsrv-sektioner.

  5. Ta bort phpinfo() sidan.

Testa båda PHP-API:erna

Spara detta program som 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);

Kör det först från kommandoraden:

php verify-php-drivers.php

Förväntat resultat:

SQLSRV and PDO_SQLSRV are available.

Om du behöver verifiera en webbruntime, placera filen tillfälligt i webbplatsens dokumentrot och öppna den i en webbläsare. Ta bort den efter testning. Detta program verifierar PHP-API:erna utan att kräva eller exponera databasautentiseringsuppgifter.

Testa en databasanslutning

Inläsning av tillägg är bara den första kontrollen vid installationen. Testa båda API:erna mot databasmålet som applikationen använder, så testet täcker även ODBC-drivrutinen, nätverksväg, kryptering, autentisering, frågeexekvering, returnerade värden och rensning.

Sätt temporära miljövariabler i PowerShell genom att svara på prompter. Ange server- och databasnamn som råvärden, utan citattecken eller drivrutinskodning. Använd inloggningsdialogen eller prompten för ett testkonto som kan ansluta till databasen. Inkludera inte inloggningsuppgifter i en kommandorad eller inspelad terminalsession:

$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

Inloggningsuppmaningen döljer lösenordet. Miljön innehåller klartextlösenordet så att PHP kan läsa det. Använd dessa variabler endast under testsessionen, skriv inte ut dem, och rensa dem efter testning.

Spara detta program som test-php-drivers.php. Behåll miljövariablerna oförändrade. Programmet dubblar avslutande klammerparenteser och lägger till yttre klammer innan programmet skickar databasnamnet, användarnamnet och lösenordet vidare till drivrutinen. Denna kodning bevarar bokstavliga klamrar och förhindrar semikolon från att separera anslutningsalternativ.

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

Kör programmet med samma PHP-exekverbara fil som du verifierade:

php test-php-drivers.php

Förväntat resultat:

SQLSRV query: 1
PDO_SQLSRV query: 1

Om tilläggskontrollen klaras men detta program misslyckas, använd SQLSTATE och den inbyggda felkoden för att identifiera det ägande lagret. Installera inte om PHP-tilläggen vid nätverks-, certifikat-, autentiserings- eller databasbehörighetsfel.

Ta bort skriptet och temporära variabler efter 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

Symtom Vad du bör kontrollera Reparera
Could not open input file: .\pie.phar Nuvarande mapp och nedladdningsplats Gå tillbaka till katalogen som innehåller den verifierade PHAR, eller ladda ner och verifiera den igen
Unable to load dynamic library extension_dir, exakt DLL-namn, PHP-minorversion, arkitektur och trådsäkerhetsläge Välj den matchande DLL:n eller kör om PIE med den avsedda PHP-exekverbara filen
The specified module could not be found Drivrutins-DLL-beroenden Bekräfta att tillägget DLL finns, installera den matchande Visual C++ Redistributable, och inspektera eventuellt kvarvarande saknat DLL-beroende
CLI laddar båda drivrutinerna men IIS gör det inte Annan PHP-exekverbar fil eller php.ini Jämför php --ini med phpinfo(), konfigurera IIS-runtimen och starta om FastCGI
Module "sqlsrv" is already loaded Både PIE- och ZIP-poster, eller upprepade poster Behåll en SQLSRV-post och en PDO_SQLSRV post
PDO-rapporter could not find driver PDO_SQLSRV konfiguration Kör php --ri pdo_sqlsrv och kontrollera PDO::getAvailableDrivers()
PIE rapporterar framgång men en gammal version finns kvar Versionshanterade ZIP-posterna är fortfarande aktiva Byt ut gamla poster mot PIE:s oversionerade DLL-poster och starta om varje PHP-process

Om båda tilläggen laddas kan PHP anropa deras API:er. Fånga SQLSRV-fel eller ett PDO-undantag innan du ändrar drivrutinsfiler. Fel i nätverk, autentisering, kryptering, certifikat och databasbehörigheter åtgärdas inte genom att installera om PHP-tillägget.

Relaterat innehåll

  • Uppdaterades senast