Windows'ta SQL Server için PHP sürücülerini yükleyin

Bu makaleyi kullanarak Windows'a PHP için SQLSRV ve PDO_SQLSRV sürücülerini yükleyin. Sürücüler, Microsoft ODBC Driver for SQL Server'ı kullanan PHP uzantılarıdır.

Başlamadan önce, PHP sürümünüzün, mimarinizin ve iş parçacığı güvenliği modunuzun destek matrisinde desteklendiğini doğrulayın. Komut satırı işlemi tarafından kullanılan PHP çalışma zamanı ile web sunucusu tarafından kullanılan PHP çalışma zamanı, farklı php.ini dosyaları kullanabilir. Her çalışma zamanını ayrı ayrı yapılandırın ve doğrulayın.

İşlemin sonunda, hem sqlsrv_connect() hem de PDO sqlsrv sürücüsü, amaçlanan CLI veya web uygulaması için kullanılabilir olmalı ve her API bir test sorgusunu tamamlamalıdır. Başarılı bir dosya kopyası tek başına tamamlanmış bir kurulum değildir.

Bir yükleme yöntemi seçin

Method	Şu durumlarda kullanın:	Neleri yükler
Uzantılar için PHP Kurulumcusu (PIE)	Kurulumcunun PHP çalıştırılabilir dosyası için sürücü derlemesini seçmesini istersiniz	Sürümsüz php_sqlsrv.dll ve php_pdo_sqlsrv.dll, otomatik yapılandırma denemesiyle
Yayımlanan ZIP paketi	Tam olarak hazırlanmış dosyaları kendiniz seçmeli, incelemeli veya devreye almalısınız	PHP minör sürümüne, iş parçacığı güvenliği moduna ve mimariye göre seçilen versiyonlu DLL'ler

Her iki uzantı için de bir yöntem kullanın. PIE ve ZIP yapılandırma girişlerini aynı anda aktif tutmayın.

Önkoşulları yükleme

1. PHP for Windows sitesinden desteklenen bir PHP derlemesi kurun. PHP dizinini PATH içine ekleyin.

2. PHP yapınız için gereken Visual C++ Redistributable'ı yükleyin. PHP for Windows gereksinimlerinde açıklandığı gibi x64 veya x86 mimarisini PHP ile eşleştirin.

3. SQL Server için en son Microsoft ODBC Sürücüsünü yükleyin.

4. PHP çalışma zamanı ve yapılandırma dosyasını doğrulamak için aşağıdaki komutları çalıştırın:

   php --version
   php --ini
   

   Eğer Yüklü Yapılandırma Dosyası(none) ise, PHP dizininde php.ini-development öğesini php.ini konumuna kopyalayın.

5. Içinde php.ini, uzantı dizinini ayarlayın ve PHP Eklenti Yükleyicisi (PIE) tarafından gerekli olan uzantıları etkinleştirin:

   extension_dir = "ext"
   extension=openssl
   extension=zip
   

6. PHP'nin ön koşullar eklentilerini bulabildiğini doğrulayın:

   php --ri openssl
   php --ri zip
   

   PIE'yi indirmeden önce bu ön koşulları düzeltin.

PIE ile kur

PIE , PHP çalışma zamanı için eşleşen önceden derlenmiş sürücüyü yükler. Windows'ta C derleyicisi gerektirmiyor.

1. Yazabileceğiniz bir dizine geçin ve en son PIE PHP arşivini (PHAR) indirin:

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

   Kalan PIE komutları dosyaya .\pie.phar olarak başvurur, bu nedenle bunları aynı dizinden çalıştırın.

   PHAR'ı çalıştırmadan önce, GitHub komut satırı arayüzü (CLI) ile doğrulayın:

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

   Devam etmeden önce indirmeyi onaylayın:

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

2. Her sürücüyü ayrı ayrı yükleyin:

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

3. Komut satırı çalışma zamanını doğrulayın:

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

PIE, komut satırı çalıştırılabilir dosyasının kullandığı yapılandırmadaki uzantıları etkinleştirmeye çalışır. PIE, bir uzantı etkinleştiremediğini bildirirse, PIE'ye özgü uzantı girişlerini ekleyin.

Web sunucunuz başka bir PHP kurulumu kullanıyorsa, yapılandırmadan önce o kurulumun PHP sürümü, mimarisi ve iş parçacığı güvenlik modu için her iki sürücüyü de yükleyin. Aynı PHP kurulumu web sunucusu için farklı bir php.ini kullanıyorsa, o dosyadaki yüklü sürücüleri etkinleştirin. Web çalışma zamanını ayrı olarak doğrulayın ve yapılandırmasını değiştirdikten sonra web sunucusunu yeniden başlatın.

PIE, seçilen PHP kurulumunu değiştirir. IIS'i yapılandırmaz, bir IIS sitesi seçmez veya mevcut PHP süreçlerini yeniden başlatmaz.

Yayımlanmış bir ZIP paketini manuel olarak kur

Sürücü dosyalarını kendiniz seçmeniz gerektiğinde veya PIE uygun olmadığında bu yöntemi kullanın.

1. Yayınlanan sürücü sürümü için Windows ZIP'ini Microsoft Drivers for PHP for SQL Server sürümleri sayfasından indirin.

2. php -i | findstr /I "PHP Version Thread Safety Architecture extension_dir" komutunu çalıştırın ve PHP sürümünü, iş parçacığı güvenlik modunu, mimariyi ve uzantı dizinini kaydedin.

3. ZIP'den, eşleşen her iki dinamik bağlantı kütüphanesini (DLL) uzantı dizinine kopyalayın:

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

   Örneğin, bir PHP 8.5 x64 iş parçacığı güvenli çalışma zamanı php_sqlsrv_85_ts_x64.dll ve php_pdo_sqlsrv_85_ts_x64.dllkullanır.

4. Çalışma zamanı tarafından kullanılan php.ini öğesine eşleşen uzantı adlarını ekleyin:

   extension=php_sqlsrv_85_ts_x64.dll
   extension=php_pdo_sqlsrv_85_ts_x64.dll
   

   ts, x64 ve 85 öğelerini PHP çalışma zamanınızın değerleriyle değiştirin. İş parçacığı güvenli ve iş parçacığı güvenli olmayan dosyaları, 32-bit ve 64-bit dosyaları veya başka bir PHP minör sürümü için oluşturulmuş dosyaları karıştırmayın.

5. Çalışma zamanını php --ri sqlsrv, php --ri pdo_sqlsrv ve php -m ile doğrulayın. Bir web sunucusu için, geçici bir sayfa oluşturmadan önce phpinfo(). Yüklü Yapılandırma Dosyasını ve her iki sürücü bölümünü doğrulayın, ardından sayfayı kaldırın.

Bir web sunucusunu yapılandırın

IIS için, hedeflenen php-cgi.exe öğesini PHP IIS kurulum rehberini izleyerek bir FastCGI uygulaması olarak yapılandırın. FastCGI uygulamasının, sürücüleri kurmak için kullandığınız aynı PHP dizini ve mimarisini kullandığını doğrulayın.

Herhangi bir Windows web sunucusu için:

1. phpinfo(). Web sunucusunun PHP yürütülebilir dosyasını ve etkin php.ini ögesini belirleyin.

2. Web çalışma zamanı için her iki bileşenin de yüklü olduğundan emin olun. Ayrı bir PHP kurulumu için, o kurulumun PHP çalıştırılabilir dosyasıyla PIE kullanın veya her iki eşleşen DLL'yi yayımlanan ZIP'ten ilgili kurulumun uzantı dizinine kopyalayın. Sürücü girişlerini, yalnızca php.ini CLI'dan farklı olduğunda da dahil olmak üzere web çalışma zamanının yapılandırmasına ekleyin.

3. Web sunucusunu veya FastCGI işlemlerini yeniden başlatın.

4. Sayfanın ayrı sqlsrv ve pdo_sqlsrv bölümler içerdiğini doğrulayın.

5. Sayfayı phpinfo() kaldırın.

Her iki PHP API'sini de test edin

Bu programı verify-php-drivers.php olarak kaydedin:

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

Önce komut satırından çalıştırın:

php verify-php-drivers.php

Beklenen çıkış:

SQLSRV and PDO_SQLSRV are available.

Bir web çalışma zamanını doğrulamanız gerekiyorsa, dosyayı geçici olarak sitenin belge köküne yerleştirin ve bir tarayıcıda açın. Test ettikten sonra çıkarın. Bu program, veritabanı kimlik bilgilerini gerektirmeden veya açığa çıkarmadan PHP API'lerini doğrular.

Veritabanı bağlantısını test et

Uzantı yüklemesi sadece ilk kurulum kontrolüdür. Her iki API'yi de uygulamanın kullandığı veritabanı hedefiyle test edin; böylece test aynı zamanda ODBC sürücüsü, ağ yolu, şifreleme, kimlik doğrulama, sorgu yürütme, geri dönen değerler ve temizliği de kapsar.

PowerShell'de geçici ortam değişkenlerini sorgulara cevap vererek ayarlayın. Sunucu ve veritabanı isimlerini, tırnak veya sürücü kodlaması olmadan ham değer olarak girin. Veritabanına bağlanabilen bir test hesabı için kimlik bilgisi diyalogunu veya kimlik bilgisi istemini kullanın. Kimlik bilgilerini komut satırına veya kayıtlı terminal oturumuna dahil etmeyin:

$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

Kimlik bilgileri istemi parolayı gizler. Ortam, PHP okuyabilsin diye düz metin şifresini içerir. Bu değişkenleri sadece test oturumunda kullanın, yazdırmayın ve test sonrası temizleyin.

Bu programı test-php-drivers.php olarak kaydedin. Çevre değerlerini değiştirmeden tutun. Program, kapanış süslü parantezlerini çiftler ve dış süslü parantezler ekler, ardından veritabanı adı, kullanıcı adı ve şifreyi sürücüye iletir. Bu kodlama, literal küme parantezlerini korur ve noktalı virgüllerin bağlantı seçeneklerini ayırmasını engeller.

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

Programı, doğruladığınız aynı PHP çalıştırılabilir dosyayla çalıştırın:

php test-php-drivers.php

Beklenen çıkış:

SQLSRV query: 1
PDO_SQLSRV query: 1

Eğer uzantı kontrolü geçerse ama bu program başarısız olursa, sahibi olan katmanı belirlemek için SQLSTATE ve yerel hatasını kullanın. Ağ, sertifika, kimlik doğrulama veya veritabanı izni hatası için PHP uzantılarını yeniden yüklemeyin.

Testten sonra script ve geçici değişkenleri kaldırı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

Belirti	Denetlenecek şeyler	Düzelt
Could not open input file: .\pie.phar	Mevcut dizin ve indirme konumu	Doğrulanmış PHAR'ı içeren dizine geri dönün veya tekrar indirip doğrulayın
Unable to load dynamic library	extension_dir, tam DLL adı, PHP minör sürümü, mimari ve iş parçacığı güvenliği modu	Eşleşen DLL'yi seçin veya PIE'yi amaçlanan PHP çalıştırılabilir dosyayla tekrar çalıştırın
The specified module could not be found	Driver DLL bağımlılıkları	Uzantı DLL'nin var olduğunu doğrulayın, eşleşen Visual C++ Redistributable'ı yükleyin ve kalan eksik DLL bağımlılığını inceleyin
CLI her iki sürücüyü de yüklüyor ama IIS yüklemiyor	Farklı PHP yürütülebilir dosyası veya php.ini	php --ini ile phpinfo() karşılaştırın, IIS çalışma zamanını yapılandırın ve FastCGI'yi yeniden başlatın
Module "sqlsrv" is already loaded	Hem PIE hem ZIP girişleri ya da tekrarlanan girişler	Bir SQLSRV girişi ve bir PDO_SQLSRV girişi sakla
PDO rapor eder could not find driver	PDO_SQLSRV yapılandırması	Çalıştırın php --ri pdo_sqlsrv ve kontrol edin PDO::getAvailableDrivers()
PIE başarı bildiriyor ama eski bir versiyon hâlâ kalıyor	Versiyonlu ZIP girişleri hâlâ aktif	Eski kayıtları PIE'nin sürümsüz DLL girişleriyle değiştirin ve her PHP sürecini yeniden başlatın

Her iki uzantı da yüklenirse, PHP API'lerini çağırabilir. Sürücü dosyalarını değiştirmeden önce SQLSRV hatalarını veya PDO istisnasını yakalayın. Ağ, kimlik doğrulama, şifreleme, sertifika ve veritabanı izni hataları PHP uzantısını yeniden yükleyerek düzeltilmez.

İlgili içerik

• SQL Server için Microsoft Drivers for PHP için sistem gereksinimleri
• SQL Server için PHP için Microsoft Sürücüleri'ni yükleme
• SQL Server için PHP sürücülerini yükseltin