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'den veri okumak ve yazmak için kullanabileceğiniz PHP eklentileridir. İki uzantı aynı Microsoft ODBC Driver for SQL Server'ı kullanır, ancak farklı PHP API'leri ve sürücüye özgü seçenekler sunarlar:

• SQLSRV, SQL Server özelliklerine uyarlanmış prosedürel bir API (sqlsrv_*fonksiyonlar) sunar.
• PDO_SQLSRV, PHP Veri Nesneleri (PDO) arayüzünü uygular. PDO çağrılarını mevcut veritabanı kodunda tutabilirsiniz, ancak veritabanlarını değiştirmeden önce koddaki sorguları ve sürücüye özgü ayarları gözden geçirin.

Her iki sürücü de Azure SQL Veritabanı, Microsoft Fabric'teki SQL veritabanı, Azure SQL Yönetilen Örneği ve Express sürümleri dahil olmak üzere desteklenen tüm SQL Server sürümleri ve edisyonları ile bağlantı kurar. Her iki sürücü de PHP akışlarını giriş parametresi olarak kabul eder. SQLSRV, büyük ikili ve karakter değerlerinin akış olarak alınmasını destekler. PDO_SQLSRV'nin aynı çıkış akışı davranışına sahip olduğunu varsaymayın.

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

• Kurulumunuzu doğrulamak ve SQLSRV veya PDO_SQLSRV kullanarak parametreli bir sorgu çalıştırmak için Hızlı Başlangıç: PHP için Microsoft Sürücüleriyle bağlanma ve sorgu oluşturma ile başlayın.
• Sürücüyü Linux veya macOS'a yüklemek için, Linux ve macOS için Kurulum eğitimi ile başlayın ve SQL Server için PHP için Microsoft Sürücülerini indirin.
• Azure SQL'e şifresiz kimlik doğrulama ile bağlanmak için, Microsoft Entra kimlik doğrulama ve Bağlantı seçenekleriyle Connect ile başlayın.
• Mevcut bir uygulamayı geçici arızalara karşı dayanıklı hale getirmek için Boşta bağlantı dayanıklılığı sayfasına gidin.
• SQLSRV ile PDO_SQLSRV arasında karar vermek için, SQL Server için PHP için Microsoft sürücülerin genel görünümü ve Yürütme fonksiyonlarını karşılaştırma bölümlerine gidin.
• Bir kurulum, bağlantı veya sorgu sorununu teşhis etmek için Sorun Giderme, Hataları ve uyarıları işleme ile Faaliyet Kaydı bölümlerine gidin.
• Mevcut bir uygulamayı daha hızlı hale getirmek için Performance Tuning'e gidin.

Azure SQL için üretim temeli

Bu PDO_SQLSRV örnek, sunucuyu ve veritabanını ortam değişkenlerinden okur ve yönetilen bir kimlikle bağlanır. Bir veri kaynağı adı (DSN) oluşturur ve sertifika doğrulama ile Taşıma Katmanı Güvenliği'ni (TLS) etkinleştirir. Bu değerleri web isteği parametrelerinden değil, güvenilir uygulama yapılandırmasından okuyun. Kimliğe veritabanına erişim izni verdikten sonra programı, yönetilen kimlik uç noktasına sahip bir ana bilgisayarda çalıştırın.

Yardımcı fonksiyonlar, listelenen bir hata meydana geldiğinde bağlanmak veya salt okunur sorguyu çalıştırmak için en fazla üç deneme yapar. Denemeler arasında daha uzun süre beklerler; bu yeniden deneme desenine exponential backoff denir. Bir sorgu hatası yeni bağlantı gerektiriyorsa, sorgu yardımcısı çağıran kodun işletmesi için istisna atar.

Desteklenen bir PHP sürümü, PDO_SQLSRV uzantısı ve SQL Server için Microsoft ODBC Driver 18 kullanın. Desteklenen kimlik doğrulama değerleri için bkz. Microsoft Entra kimlik doğrulamasını kullanarak bağlanma. Uygulamaya özgü bir yeniden deneme politikası tasarlamadan yazma veya çoklu ifade işlemleri için sorgu yardımcısını yeniden kullanmayın: bir hata her zaman bir yazma işleminin commit edilip edilmediğini söylemez.

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

// This read helper retries only the listed errors on the same connection.
// Other errors propagate; the caller must decide whether to reconnect.
const RETRYABLE_READ_ERROR_CODES = [1205, 1222, 40501, 10928, 10929];

/**
 * 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);
            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');
}

/**
 * Retry the standalone read-only query for errors that allow connection reuse.
 */
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, RETRYABLE_READ_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.');
}
$databaseValue = '{' . str_replace('}', '}}', $database) . '}';

$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,
    $databaseValue
);

$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 name FROM sys.databases WHERE database_id > ? ORDER BY name', [1]);
foreach ($stmt as $row) {
    echo $row['name'], PHP_EOL;
}

Bu ayarları Azure SQL Veritabanı failover groups ve Azure SQL Yönetilen Örneği için kullanın.

• Driver={ODBC Driver 18 for SQL Server} sürücü keşfine güvenmek yerine ODBC Sürücü 18'i açıkça seçer. Örneği çalıştırmadan önce kur.

• SQL_DATABASE öğesini gerçek veritabanı adına ayarlayın. Program, kapanış desteklerini çift yapar ve ismi desteklerle kaplar, ardından DSN'ye yerleştirir. Escaping, isimdeki özel karakterlerin sürücünün bağlantı ayarlarını nasıl okumasını değiştirmesini engelliyor.

• ConnectRetryCount ve ConnectRetryInterval ODBC boşta bağlantı dayanıklılığını kontrol eder. İfadenin sorgu zaman aşımı, yürütme sırasında kurtarmayı sınırlar. Örneklemin 30 saniyelik sorgu zaman aşımıyla, ODBC beş yeniden bağlantı denemesinin tamamını tüketmeden durabilir. LoginTimeout=90 bağlantı kurulumunu kontrol eder, kurtarma bütçesini değil. Uygulama düzeyindeki yardımcı oyuncu seçilen sunucu hatalarını tekrar dener; sorgu zamanlamasını tekrar denmez veya kısmen alınan sonuçları tekrar oynatmaz.

• Programın çağrılarıyla error_log() birlikte sürücü kaydını etkinleştirin. PDO_SQLSRV için, çalıştırma zamanı veya php.ini ile ini_set() birlikte pdo_sqlsrv.log_severity ayarlanabilir. SQLSRV için, yapılandırın LogSeverity ve LogSubsystems ile sqlsrv_configure(). 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ı. Kimliği DSN'e gömmek yerine PDO constructor'ının kullanıcı adı argümanını 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.

• Okunma ölçeklendirme veya okunabilir ikincil için DSN'e ekleyin ApplicationIntent=ReadOnly .

• SQL servisinizin sağladığı uç noktayı, buluta özgü alanı da dahil olmak üzere, kullanın. Sertifika doğrulamasını devre dışı bırakmak yerine sertifika-isim uyumsuzluklarını araştırın. Sadece o uç nokta için beklenen sertifika adını bildiğinizde kullanın HostNameInCertificate .

• ODBC, yönetilen kimlik ve hizmet sorumlusu kimlik doğrulaması için tokenlar edinir. Ile AccessToken, uygulamanız tokenı alır ve sürücüye aktarır; ODBC sizin için edinmez. Daha fazla bilgi için ODBC Sürücüsü ile Microsoft Entra ID'yi kullanma konusuna bakın.

• Bağlantı bilgilerini kodunun dışında tut. Uygulamanızın yapılandırma sisteminde depolayın ve sırlar için Azure Key Vault'u kullanın.

• SQLSRV ile, dizideki bağlantı seçeneklerini ayarlamak .sqlsrv_connect() Bir false dönüş değeri olup olmadığını kontrol edin ve yeniden denemeye karar vermeden önce sqlsrv_errors() öğesini inceleyin. Açıklama zamanlamalarını ayrı olarak ayarlayın .QueryTimeout Boşta bağlantı dayanıklılığı, uygulama düzeyinde bir yeniden deneme döngüsü değil, ODBC yeniden bağlantısını gösterir.

• 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:

• Bağlantı seçenekleri
• Microsoft Entra kimlik doğrulamayı kullanarak bağlanma
• Boşta bağlantı dayanıklılığı
• Microsoft Azure SQL Veritabanı'na bağlanma
• Yüksek Kullanılabilirlik Desteği, felaket kurtarma

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

Temel özellikler

• İki PHP API'si: SQLSRV prosedürel fonksiyonlar sağlar. PDO_SQLSRV, PDO'yu gerçekler. Ya uzantı ya da ikisini de takın.
• 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ı: Yönetilen kimlik, hizmet sorumlusu ve harici olarak edinilen erişim tokenları, Microsoft ODBC Driver for SQL Server üzerinden sağlanır. Yönetilen kimlik şifresizdir; ActiveDirectoryServicePrincipal bir istemci sırrı kullanır.
• Always Encrypted: İstemci üzerindeki hassas sütunları şifreleyin; şifrelenmiş veriler üzerinde desteklenen işlemler için 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ı: Akış parametrelerinden büyük ikili ve karakter değerleri gönderin, iki API'den biriyle. Akışlı alım için SQLSRV kullanı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.
Hızlı Başlangıç: Microsoft PHP Sürücüleri ile bağlanın ve sorgulayın	Uzantıları doğrulayın, bir bağlantı yapılandırın ve aynı parametreli sorguyu SQLSRV veya PDO_SQLSRV ile çalıştırın.
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	Windows'ta entegre kimlik doğrulama veya Linux ve macOS'ta Kerberos 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 de programlama görevlerini bul.
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	Bir grup ifadeyi birlikte commit edin veya geri alın.
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	SQLSRV'nin CharacterSet seçeneğini veya PDO_SQLSRV'nin PDO::SQLSRV_ATTR_ENCODING özniteliğini ayarlayı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.

İlgili görevler

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ı.

Özellik isteme

Bir özellik talep etmek için, Microsoft Drivers for PHP for SQL Server GitHub deposunda bir sorun açın.

İlgili içerik

• Microsoft Drivers for PHP for SQL Server on GitHub
• SQL Server için Microsoft ODBC Sürücüsü
• Microsoft SQL sürücüleri ve çerçeveleri