SQL Server için PHP için Microsoft Sürücüleri

PHP sürücüsünü indirme

Microsoft Drivers for PHP for SQL Server, PHP betiklerinden Microsoft SQL Database Engine'de veri okumanızı ve yazmanızı sağlayan PHP eklentileridir. Paket, aynı Microsoft ODBC Driver for SQL Server'ı saran ve aynı bağlantı seçeneklerini paylaşan iki sürücü gönderiyor, böylece kod tabanınıza uygun API'yi seçebilirsiniz:

  • SQLSRV, SQL Server özelliklerine uyarlanmış prosedürel bir API (sqlsrv_*fonksiyonlar) sunar.
  • PDO_SQLSRV, PHP Veri Nesneleri (PDO) arayüzünü uygular, böylece diğer veritabanları için zaten PDO kullanan kod minimum değişiklikle SQL Server hedefleyebilir.

Her iki sürücü de Azure SQL Veritabanı'e, Microsoft Fabric'teki SQL veritabanı, Azure SQL Yönetilen Örneği'a ve desteklenen tüm SQL Server sürümlerine (Express sürümleri dahil) bağlanır. Büyük ikili ve karakter değerlerini tamamen belleğe yüklemeden aktarmak için PHP akışlarını kullanırlar.

Başlangıç noktanızı seçin

Azure SQL için üretim temeli

Bu snippeti, PDO_SQLSRV sürücüsüyle üretim odaklı Azure SQL bağlantı için bir başlangıç noktası olarak kullanın. Sunucu ve veritabanını ortam değişkenlerinden (örneğin Azure App Service uygulama ayarlarından) okur, yönetilen bir kimlik ile kimlik doğrulamasını sağlar, sunucu sertifikası doğrulamasıyla Taşıma Katmanı Güvenliği'ni (TLS) etkinleştirir, soğuk başlatma devre devremesini kapsayan bir giriş zaman aşımını ayarlar ve SQL Server boşta bağlantı dayanıklılığını ayarlar ConnectRetryCountConnectRetryInterval. Uygulama düzeyindeki connectWithRetry ve queryWithRetry yardımçılar, hem ilk bağlantıyı hem de her ifadeyi sınırlı üstel geri dönüşle sarar ve geçici bağlantı hatalarını (yeni bağlantı gerektiren) geçici sorgu hatalarından (aynı bağlantıyı tekrar kullanan) ayırır.

PHP 8.0 ve daha sonraki sürümleri, PDO_SQLSRV uzantısı ve SQL Server 17.3.1.1 ile daha sonraki sürümler Authentication=ActiveDirectoryMsiiçin Microsoft ODBC Sürücüsü gerektirir. Desteklenen Authentication değerlerin tam listesi için bkz. Connect using Microsoft Entra authentication.

<?php
declare(strict_types=1);

// Transient errors that require a fresh connection to recover. SQLSTATE values
// starting with '08' cover ODBC connection-established and connection-broken
// states (for example, 08001, 08S01).
const CONNECT_RETRY_SQLSTATE_PREFIX = '08';

// SQL Server error codes that are transient regardless of when they surface:
// 1205 (deadlock victim), 1222 (lock request timeout), and the Azure SQL
// throttling, mid-query failover, and "database not currently available"
// codes that arrive with SQLSTATE HY000.
const TRANSIENT_SERVER_ERROR_CODES = [1205, 1222, 40501, 40613, 40197, 10928, 10929, 49918];

/**
 * Open a connection, retrying transient failures with exponential backoff.
 */
function connectWithRetry(string $dsn, array $options, int $maxAttempts = 3): PDO
{
    for ($attempt = 1; $attempt <= $maxAttempts; $attempt++) {
        try {
            $pdo = new PDO($dsn, null, null, $options);
            error_log(sprintf('connected on attempt %d/%d', $attempt, $maxAttempts));
            return $pdo;
        } catch (PDOException $e) {
            $sqlstate = (string) $e->getCode();
            $driverCode = isset($e->errorInfo[1]) ? (int) $e->errorInfo[1] : 0;
            $isTransient = str_starts_with($sqlstate, CONNECT_RETRY_SQLSTATE_PREFIX)
                || in_array($driverCode, TRANSIENT_SERVER_ERROR_CODES, true);
            if (!$isTransient || $attempt === $maxAttempts) {
                error_log(sprintf('connect failed on attempt %d/%d: %s', $attempt, $maxAttempts, $e->getMessage()));
                throw $e;
            }
            $delay = 2 ** ($attempt - 1); // 1, 2, 4 seconds
            error_log(sprintf('connect attempt %d hit transient %s/%d; retrying in %d seconds', $attempt, $sqlstate, $driverCode, $delay));
            sleep($delay);
        }
    }
    throw new RuntimeException('connectWithRetry exhausted retries');
}

/**
 * Run a parameterized query, retrying transient statement failures on the same
 * connection. Deadlocks (1205) roll back the transaction before the driver sees
 * the error, so rerunning a single statement is safe. If the statement was part
 * of a multistatement transaction, wrap the whole transaction in your own retry
 * loop so earlier statements replay too.
 */
function queryWithRetry(PDO $pdo, string $sql, array $params = [], int $maxAttempts = 3): PDOStatement
{
    for ($attempt = 1; $attempt <= $maxAttempts; $attempt++) {
        try {
            $stmt = $pdo->prepare($sql);
            $stmt->execute($params);
            return $stmt;
        } catch (PDOException $e) {
            $driverCode = isset($e->errorInfo[1]) ? (int) $e->errorInfo[1] : 0;
            $isTransient = in_array($driverCode, TRANSIENT_SERVER_ERROR_CODES, true);
            if (!$isTransient || $attempt === $maxAttempts) {
                error_log(sprintf('query failed on attempt %d/%d: %s', $attempt, $maxAttempts, $e->getMessage()));
                throw $e;
            }
            $delay = 2 ** ($attempt - 1);
            error_log(sprintf('query attempt %d hit transient code %d; retrying in %d seconds', $attempt, $driverCode, $delay));
            sleep($delay);
        }
    }
    throw new RuntimeException('queryWithRetry exhausted retries');
}

// Load endpoint details from application configuration. In Azure App Service,
// these can come from app settings or Key Vault-backed settings.
$server = getenv('SQL_SERVER') ?: null;
$database = getenv('SQL_DATABASE') ?: null;

if ($server === null || $database === null) {
    throw new RuntimeException('Set SQL_SERVER and SQL_DATABASE in your application configuration.');
}

$dsn = sprintf(
    'sqlsrv:Driver={ODBC Driver 18 for SQL Server};Server=%s;Database=%s;'
    . 'Encrypt=true;TrustServerCertificate=false;'
    . 'LoginTimeout=90;Authentication=ActiveDirectoryMsi;'
    . 'ConnectRetryCount=5;ConnectRetryInterval=15;'
    . 'MultiSubnetFailover=true;',
    $server,
    $database
);

$options = [
    PDO::ATTR_ERRMODE               => PDO::ERRMODE_EXCEPTION,
    PDO::ATTR_DEFAULT_FETCH_MODE    => PDO::FETCH_ASSOC,
    PDO::ATTR_EMULATE_PREPARES      => false,
    PDO::SQLSRV_ATTR_QUERY_TIMEOUT  => 30,
];

$pdo = connectWithRetry($dsn, $options);
$stmt = queryWithRetry($pdo, 'SELECT TOP (?) name FROM sys.databases ORDER BY name', [5]);
foreach ($stmt as $row) {
    echo $row['name'], PHP_EOL;
}

Bu kod parçacığı, Azure SQL Veritabanı yük devretme grupları ve Azure SQL Yönetilen Örneği için ayarlanmıştır.

  • Driver={ODBC Driver 18 for SQL Server} ODBC 18 sürücüsünü sabitler. Eğer ana bilgisayarda ODBC 17 de yüklüyse, PDO_SQLSRV ODBC 17'ye bağlanabilir. Eski 17.x derlemeleri yeni Authentication değerleri reddeder; örneğin, Authentication=ActiveDirectoryMsi ODBC 17.3.1.1 veya daha sonraki sürümleri gerektirir. Bkz. bağlantı dizesi özniteliği 'Authentication' için belirtilen geçersiz değer.

  • ConnectRetryCountve ConnectRetryInterval SQL Server boşta bağlantı dayanıklılığını sağlayan ODBC bağlantı dizesi anahtar kelimeleridir: sürücü, bozuk bir boşta bağlantıyı şeffaf şekilde yeniden bağlar. Bu, geçici bir hata (örneğin kilitlenme veya sorgu zaman aşımı) nedeniyle başarısız olan bir deyimi yeniden deneyen uygulama düzeyindeki queryWithRetry yapısından farklıdır. İkisi tamamlayıcı, ikisini de sakla. LoginTimeout değerinin en az ConnectRetryCount * ConnectRetryInterval olduğundan emin olun; böylece boştayken yeniden bağlanma akışı kendisine ayrılan sürenin tamamını kullanabilir. Örnekte, 5 × 15 saniyelik yeniden denemeleri karşılamak ve soğuk yük devretmede ilk oturum açma için ek pay bırakmak üzere 90 saniye kullanılır.

  • Uygulama düzeyindeki error_log() çağrıları sürücü tarafı tanılamalarla tamamlayın. PDO_SQLSRV için, pdo_sqlsrv.log_severity’ı php.ini içinde ayarlayın (yalnızca başlatma sırasında ayarlanabilir); SQLSRV için, çalışma zamanında sqlsrv_configure("LogSubsystems", ...) çağrısını yapın. Daha fazla bilgi için Kayıt faaliyetleri bölümünü inceleyebilirsiniz.

    ; php.ini - enable PDO_SQLSRV driver diagnostics alongside the application-level
; error_log() calls in the sample. Use 1 (errors) in production; -1 (all) is
; useful during triage but very chatty.
[pdo_sqlsrv]
pdo_sqlsrv.log_severity = 1

  • Kullanıcı tarafından atanan bir yönetilen kimlik için, kimliğin kimlik numarasını PDO'nun $username argümanı olarak (new PDO($dsn, $identityId, null, $options)) iletin. istemci kimliğiniAzure App Service veya Azure Container Instance üzerinde kullanın; aksi takdirde nesne kimliğini kullanın. PHP sürücüleri bu davranışı altta yatan Microsoft ODBC Driver for SQL Server'dan miras alır; daha fazla bilgi için bkz. ODBC Sürücüsü ile Microsoft Entra ID'nin Kullanılması. PDO_SQLSRV, DSN’nin kendi içinde UID ifadesini kabul etmez; bu nedenle oluşturucu parametresini kullanın. Kullanıcı olarak null değerini geçirmek (örnekte yapıldığı gibi), Azure ana bilgisayarının sistem tarafından atanan yönetilen kimliğini seçer. SQLSRV (yordamsal) için, bağlantı seçenekleri dizisinde UID geçirin.

  • Yük devretme grubu dinleyicisine, kullanılabilirlik grubu dinleyicisine veya yük devretme kümesi örneği uç noktasına bağlandığınızda MultiSubnetFailover=true olarak ayarlayın. Bu ayar, hem tek alt ağ hem de çoklu alt ağ erişilebilirlik grubu dinleyicileri için bağlantı performansını artırır. Daha fazla bilgi için Yüksek Erişilebilirlik Desteği, felaket kurtarma bölümlerine bakınız.

  • Okuma ölçek genişletmesi veya okunabilir bir ikincil için, Veri Kaynağı Adına (DSN) ApplicationIntent=ReadOnly ekleyin.

  • Sertifikanın Subject Alternative Name (SAN) alanı bağlandığınız ana bilgisayarı içermediği egemen bulutlarda, HostNameInCertificate öğesini DSN'ye ekleyin (örneğin, Azure Kamu için *.database.usgovcloudapi.net).

  • Sürücü, token edinimi için Microsoft ODBC Driver for SQL Server'a dayanır. Yönetilen kimlik, hizmet prensibi ve erişim token akışları hepsi ODBC üzerinden geçer. Daha fazla bilgi için ODBC Sürücüsü ile Microsoft Entra ID'yi kullanma konusuna bakın.

  • Daha yüksek güvenlik ve ortamlar arasında taşınabilirlik için, bağlantı bilgilerini kodunuzun dışında tutun. Bağlantı bilgilerini uygulamanızın yapılandırma sisteminde saklayın ve hassas değerler ile merkezi yönetilen bağlantı ayarları için Azure Key Vault'u kullanın.

  • Eşdeğer SQLSRV bağlantısı sqlsrv_connect($server, ['Database' => $database, 'Encrypt' => true, 'Authentication' => 'ActiveDirectoryMsi', /* ... */]) kullanır ve bir kaynağı döndürür. Yeniden deneme düzeni aynıdır: sqlsrv_connect'den gelen false dönüşünü yakalayın, SQLSTATE için sqlsrv_errors()'yi inceleyin ve yeniden denemeden önce bir süre bekleyin. Uygulamalı bir örnek için bkz: Adım 4: PHP ile SQL'e Dayanıklı Bir Şekilde Bağlanma.

  • Yeniden deneme yardımcıları, isset() tarafından korunan $e->errorInfo[1]’ı okur. PDOException::$errorInfo, ?array olarak bildirilir ve varsayılan değer olarak null kullanılır; bu nedenle koruyucu denetim 0 sürücü koduna geri döner ve yeniden deneme yapılıp yapılmayacağını SQLSTATE 08 önekinin belirlemesine olanak tanır.

Bu yapılandırmanın her bölümü hakkında daha fazla bilgi için bkz:

Azure SQL geçici hataların kataloğu için bkz. Geçici bağlantı hatalarını giderme.

Temel özellikler

  • İki API, bir sürücü paketi: SQL Server-ilk kod için prosedürel SQLSRV veya taşınabilir PDO kodu için PDO_SQLSRV.
  • Geniş platform desteği: Windows, Linux ve macOS ile desteklenen PHP sürümleriyle çalışır.
  • Şifreli bağlantılar: TLS ile şifrelenmiş bağlantılar, Encrypt=truesunucu sertifikası doğrulaması ile kontrol edilir TrustServerCertificate.
  • Microsoft Entra ID kimlik doğrulaması: Altta yatan Microsoft ODBC Driver for SQL Server üzerinden, yönetilen kimlik, hizmet sorumlusu ve erişim belirteci akışlarıyla şifresiz bağlantılar.
  • Always Encrypted: Hassas sütunlar için istemci tarafı şifreleme; yerinde işlemler için isteğe bağlı güvenli enklavlarla.
  • Bağlantı dayanıklılığı: ConnectRetryCount ve ConnectRetryInterval ile boşta kalan bağlantılar için yerleşik yeniden deneme.
  • PHP akışları: Büyük ikili ve karakter verilerini belleğe yüklemek yerine akışlar olarak okuyun ve yazın.
  • Zengin SQL Server veri türü desteği: datetimeoffset, tablo değerli parametreler, nvarchar ve PDO::SQLSRV_ENCODING_UTF8 ile Unicode.

Get started

Makale Description
Sistem gereksinimleri PHP, işletim sistemi ve SQL Server sürümlerini destekledi.
Destek matrisi PHP sürücü sürümleri için ayrıntılı uyumluluk matrisi.
SQL Server için PHP için Microsoft Sürücülerini indirin Bağlantıları indirin ve eserleri yayınlayın.
Linux ve macOS için kurulum eğitimi Sürücüyü ve ODBC ön koşullarını Linux ve macOS'a yükleyin.
Sürücülerin yüklenmesi Genişletmeleri php.ini içinde etkinleştirin.
PHP SQL sürücüsüyle başlama Dört başlangıç adımını birbirine bağlayan uçtan uca bir rehber.
PHP SQL sürücüsüne genel bakış Pakette ne var ve ne zaman SQLSRV veya PDO_SQLSRV seçilmeli.

Yapılandırma ve bağlanma

Makale Description
Sunucuya bağlanma PHP'den bir SQL Server örneğine bağlantı açın.
Bağlantı seçenekleri Bağlantı anahtar sözcükleri, varsayılanlar ve bunların nasıl ayarlanacağına ilişkin tam referans.
Microsoft Azure SQL Veritabanı'na bağlanma Bir PHP uygulamasını Azure SQL Veritabanı'e bağlayın.
Belirli bir porta bağlanın Varsayılan olmayan bir TCP portunu hedefleyin.
Bağlantı havuzu oluşturma PHP istekleri arasında ODBC bağlantılarını tekrar kullanın.
Birden Fazla Aktif Sonuç Setini (MARS) Devre Dışı Bırak Uyumluluk için MARS'ı kapatın.
LocalDB desteği Bir SQL Server LocalDB örneğine bağlanın.
Yüksek Kullanılabilirlik Desteği, felaket kurtarma Kullanılabilirlik grubu dinleyicileri ve çoklu alt ağ yük devretmesi.
Boşta bağlantı dayanıklılığı Bozulan boşta bağlantılar için otomatik yeniden bağlanma.

Authenticate

Makale Description
Microsoft Entra kimlik doğrulamayı kullanarak bağlanma Yönetilen kimlik, hizmet prensibi, erişim tokenı ve şifre akışları.
SQL Server kimlik doğrulaması ile bağlanın SQL girişini kullanıcı adı ve şifre ile kullanın.
Windows authentication ile bağlanın Alan bağlantısı olan ana bilgisayarlarda Windows entegre kimlik doğrulaması kullanın.

Secure

Makale Description
Güvenlikle ilgili dikkat edilmesi gerekenler PHP uygulamaları için tehdit modeli ve derinlemesine savunma rehberi.
Her Zaman PHP sürücüleriyle şifrelenmiştir Hassas sütunlar için istemci tarafı şifrelemesini yapılandırın.
Her Zaman Şifreli ile güvenli enklavlar Güvenli enklavlarla şifrelenmiş sütunlarda gelişmiş işlemleri mümkün kılın.

Veri alma ve güncelleme

Makale Description
Program rehberi Her iki sürücü için uçtan uca programlama rehberi.
Yürütme fonksiyonlarının karşılaştırılması İş yükünüz için doğru yürütme fonksiyonunu seçin.
Doğrudan ve hazırlanmış ifade yürütme (PDO_SQLSRV) Doğrudan yürütme yerine hazırlanmış ifadeler ne zaman kullanılacak?
Veriler alınıyor Satırları, sütunları ve akış verilerini getirme.
Verilerin güncellenmesi Satır ekle, güncelle ve sil.
Parametrizlenmiş sorgular gerçekleştirin SQL enjeksiyonuna karşı korumak için parametreleri bağlayın.
Veri akışı olarak gönder Büyük ikili ve karakter değerlerini SQL Server’a aktarın.
İşlemler yapma İfadeleri atomik işlemler halinde grupla.
Tablo değerli parametreleri kullanın Bir TABLE parametreyi depolanmış bir prosedüre ilet.
Bir imleç tipi belirtin ve satır seçin Sadece ileri yönlü, statik, dinamik veya tuş seti imleci seçin.

Veri türleri

Makale Description
Veri türlerinin dönüştürülmesi Sürücünün PHP tiplerini SQL Server tiplerine nasıl eşlediği.
Varsayılan SQL Server veri türleri Her PHP değeri için varsayılan SQL Server türü.
Varsayılan PHP veri türleri Her SQL Server sütun tipi için varsayılan PHP tipi.
SQL Server veri türlerini belirt (SQLSRV) Parametreleri bağlamarken SQL Server tipini geçersiz kılın.
PHP veri tiplerini belirt Getirme sırasında PHP tipini geçersiz kıl.
UTF-8 verilerini gönder ve geri getir Unicode gidiş-dönüşleri için PDO::SQLSRV_ENCODING_UTF8 kullanın.
Linux ve macOS'ta ASCII verilerini gönderin ve alın Windows olmayan ana bilgisayarlarda ASCII gidiş-dönüş işlemlerini yönetin.
Ondalık sayıları ve para birimini biçimlendirme (SQLSRV) SQLSRV sürücüsüyle ondalık ve para sütunlarını biçimlendirin.
Ondalık sayıları ve para birimlerini biçimlendirme (PDO_SQLSRV) PDO_SQLSRV sürücüsünü kullanarak ondalık ve para sütunlarını biçimlendirin.
Sistem dışı yerel ayarlar Yerel ondalık ayırıcılar ve diğer yerel değerlendirmeler.

Hatalar ve tanılamalar

Makale Description
Hata ve uyarıların işlenmesi Her iki sürücüde de hata ve uyarı yönetimi var.
Hata ve uyarı işlemeyi yapılandırma (SQLSRV) SQLSRV sürücüsünün hata ve uyarıları nasıl bildirdiğini ayarlayın.
Hataları ve uyarıları ele alın (SQLSRV) SQLSRV fonksiyonları tarafından döndürülen hataları inceleyin.
Günlük kaydı etkinliği Tanılama verilerini yakalamak için sürücü günlüğünü etkinleştirin.

Dağıtım ve işletim

Makale Description
Performans ayarlama Bağlantı yönetimi, toplu çalışma, hazırlanmış ifadeler, imleçler, bellek ve sunucu tarafı izleme.
Troubleshooting Yaygın kurulum, bağlantı, sorgu, veri türü, işlem ve konteyner sorunlarını teşhis edin.

Referans içeriği

Makale Description
SQLSRV sürücü API referansı Tüm sqlsrv_* fonksiyonlar, parametreler ve döndürme değerleri.
PDO_SQLSRV sürücü referansı PDO ve PDOStatement yöntemleri PDO_SQLSRV sürücüsü tarafından desteklenir.
Sabitleri Sürücüler tarafından ortaya çıkan sabitler, tip ve kodlama sabitleri dahil.
Makale Description
Sürüm notları Yeni özellikler, hata düzeltmeleri, platform desteğindeki değişiklikler ve indirme bağlantılarını içeren sürümlere göre geçmiş.
Dokümantasyondaki kod örnekleri hakkında Bu bölümdeki kod örnekleri tarafından kullanılan konvansiyonlar.
PHP SQL sürücüsü için kod örnekleri SQLSRV ve PDO_SQLSRV için uçtan uca örnek uygulamalar.
Destek kaynakları Topluluk ve destek kanalları.

İlgili içerik

  • Last updated on