Driver Microsoft untuk PHP dan SQL Server

Unduh driver PHP

Driver Microsoft untuk PHP untuk SQL Server adalah ekstensi PHP yang memungkinkan Anda membaca dan menulis data di Microsoft SQL Database Engine dari skrip PHP. Paket ini mengirimkan dua driver yang membungkus Microsoft ODBC Driver for SQL Server yang sama dan berbagi opsi koneksi yang sama, sehingga Anda dapat memilih API yang sesuai dengan basis kode Anda:

  • SQLSRV mengekspos API prosedural (sqlsrv_*fungsi) yang disesuaikan dengan fitur SQL Server.
  • PDO_SQLSRV mengimplementasikan antarmuka PHP Data Objects (PDO), sehingga kode yang sudah menggunakan PDO untuk basis data lain dapat menargetkan SQL Server dengan perubahan minimal.

Kedua driver terhubung ke Azure SQL Database, database SQL di Microsoft Fabric, Azure SQL Managed Instance, serta semua versi dan edisi SQL Server yang didukung (termasuk edisi Express). Mereka menggunakan aliran PHP untuk memindahkan nilai biner dan karakter besar tanpa memuatnya sepenuhnya ke memori.

Pilih titik awal Anda

Garis besar produksi untuk Azure SQL

Gunakan cuplikan ini sebagai titik awal untuk koneksi Azure SQL berorientasi produksi dengan driver PDO_SQLSRV. Aplikasi ini membaca server dan database dari variabel lingkungan (misalnya, pengaturan aplikasi Azure App Service), mengautentikasi dengan identitas terkelola, mengaktifkan Transport Layer Security (TLS) dengan validasi sertifikat server, menetapkan batas waktu login yang mencakup failover saat cold start, dan menetapkan ConnectRetryCount dan ConnectRetryInterval untuk ketahanan koneksi idle SQL Server. Helper connectWithRetry dan queryWithRetry pada tingkat aplikasi menerapkan backoff eksponensial terbatas pada koneksi awal maupun setiap statement, serta memisahkan kesalahan koneksi transien (yang memerlukan koneksi baru) dari kesalahan kueri transien (yang menggunakan kembali koneksi yang sama).

Memerlukan PHP 8.0 dan versi yang lebih baru, ekstensi PDO_SQLSRV, serta Driver ODBC Microsoft untuk versi SQL Server 17.3.1.1 dan versi yang lebih baru untuk Authentication=ActiveDirectoryMsi. Untuk daftar lengkap nilai yang didukungAuthentication, lihat Hubungkan menggunakan autentikasi Microsoft Entra.

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

Cuplikan ini dioptimalkan untuk grup failover Azure SQL Database dan Azure SQL Managed Instance.

  • Driver={ODBC Driver 18 for SQL Server} menempelkan driver ODBC 18. Jika host juga memiliki ODBC 17 terpasang, PDO_SQLSRV dapat mengikat ke ODBC 17. Versi build 17.x yang lebih lama menolak nilai Authentication yang lebih baru; misalnya, Authentication=ActiveDirectoryMsi memerlukan ODBC 17.3.1.1 atau versi yang lebih baru. Lihat Nilai tidak valid yang ditentukan untuk atribut string koneksi 'Authentication'.

  • ConnectRetryCount dan ConnectRetryInterval merupakan kata kunci string koneksi ODBC yang mengaktifkan ketahanan koneksi idle SQL Server: driver secara transparan menyambungkan kembali koneksi idle yang terputus. Itu berbeda dengan tingkat aplikasi queryWithRetry, yang mencoba kembali statemen yang gagal karena kesalahan sementara seperti deadlock atau timeout kueri. Keduanya saling melengkapi, jadi pertahankan keduanya. Pastikan LoginTimeout setidaknya ConnectRetryCount * ConnectRetryInterval agar jalur idle-reconnect mendapatkan anggaran penuhnya; sampel menggunakan 90 detik untuk menutupi 5 × 15 detik percobaan ulang plus ruang untuk login awal pada failover dingin.

  • Lengkapi panggilan pada tingkat aplikasi error_log() dengan diagnostik di sisi driver. Untuk PDO_SQLSRV, atur pdo_sqlsrv.log_severity di php.ini (hanya dapat diatur saat inisialisasi); untuk SQLSRV, panggil sqlsrv_configure("LogSubsystems", ...) saat aplikasi berjalan. Untuk informasi lebih lanjut, lihat Aktivitas pencatatan.

    ; 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

  • Untuk identitas terkelola yang diberikan pengguna , berikan ID identitas sebagai argumen PDO $username (new PDO($dsn, $identityId, null, $options)). Gunakan ID klien milik identitas tersebut di Azure App Service atau Azure Container Instance; jika tidak, gunakan ID objeknya. Driver PHP mewarisi perilaku ini dari Microsoft ODBC Driver for SQL Server; untuk informasi lebih lanjut, lihat Menggunakan Microsoft Entra ID dengan Driver ODBC. PDO_SQLSRV menolak UID di dalam DSN itu sendiri, jadi gunakan slot konstruktor. Passing null sebagai pengguna (seperti yang dilakukan sampel) memilih identitas terkelola yang diberikan sistem untuk host Azure. Untuk SQLSRV (prosedural), teruskan UID dalam array opsi koneksi.

  • Atur MultiSubnetFailover=true kapan Anda terhubung ke pendengar failover-group, pendengar grup ketersediaan, atau endpoint instance failover cluster. Mengatur opsi ini meningkatkan kinerja koneksi untuk listener grup ketersediaan subnet tunggal maupun multi-subnet. Untuk informasi lebih lanjut, lihat Dukungan untuk Ketersediaan Tinggi, pemulihan bencana.

  • Untuk peluasan baca atau sekunder yang dapat dibaca, tambahkan ApplicationIntent=ReadOnly ke Nama Sumber Data (DSN).

  • Untuk sovereign cloud di mana sertifikat Subject Alternative Name (SAN) tidak mencakup host yang Anda hubungkan, tambahkan HostNameInCertificate ke DSN (misalnya, *.database.usgovcloudapi.net untuk Azure Government).

  • Driver ini bergantung pada Microsoft ODBC Driver for SQL Server yang menjadi dasar untuk akuisisi token. Identitas terkelola, prinsipal layanan, dan alur token akses semuanya melewati ODBC. Untuk informasi selengkapnya, lihat Menggunakan Microsoft Entra ID dengan Driver ODBC.

  • Untuk keamanan dan portabilitas yang lebih tinggi antar lingkungan, simpan informasi koneksi di luar kode Anda. Simpan informasi koneksi di sistem konfigurasi aplikasi Anda, dan gunakan Azure Key Vault untuk nilai sensitif dan pengaturan koneksi yang dikelola secara terpusat.

  • Koneksi SQLSRV yang setara menggunakan sqlsrv_connect($server, ['Database' => $database, 'Encrypt' => true, 'Authentication' => 'ActiveDirectoryMsi', /* ... */]) dan mengembalikan sumber daya. Pola percobaan ulangnya sama: tangkap nilai kembalian false dari sqlsrv_connect, periksa sqlsrv_errors() untuk SQLSTATE, dan beri jeda sebelum mencoba lagi. Untuk contoh yang sudah dikerjakan, lihat Langkah 4: Terhubung dengan tahan lama ke SQL dengan PHP.

  • Fungsi pembantu percobaan ulang membaca $e->errorInfo[1] yang dijaga oleh isset(). PDOException::$errorInfo dideklarasikan sebagai ?array dan nilai defaultnya adalah null, sehingga pemeriksaan defensif menggunakan kode driver 0 sebagai cadangan dan membiarkan prefiks SQLSTATE 08 menentukan apakah perlu mencoba lagi.

Untuk informasi selengkapnya tentang setiap bagian konfigurasi ini, lihat:

Untuk katalog kesalahan sementara Azure SQL, lihat Memecahkan masalah kesalahan koneksi sementara.

Fitur utama

  • Dua API, satu paket driver: Procedural SQLSRV untuk kode SQL Server-first, atau PDO_SQLSRV untuk kode PDO portabel.
  • Dukungan platform luas: Berjalan di Windows, Linux, dan macOS dengan versi PHP yang didukung.
  • Koneksi terenkripsi: Koneksi terenkripsi TLS melalui Encrypt=true, dengan validasi sertifikat server yang dikendalikan oleh TrustServerCertificate.
  • Autentikasi Microsoft Entra ID: Koneksi tanpa kata sandi dengan identitas terkelola, prinsipal layanan, dan alur token akses melalui Microsoft ODBC Driver for SQL Server yang mendasarinya.
  • Always Encrypted: Enkripsi sisi klien untuk kolom sensitif, dengan enklave aman opsional untuk operasi di tempat.
  • Ketahanan koneksi: Koneksi idle bawaan mencoba ulang dengan ConnectRetryCount dan ConnectRetryInterval.
  • Aliran PHP: Membaca dan menulis nilai biner dan karakter besar sebagai aliran daripada memuatnya ke memori.
  • Dukungan tipe data SQL Server kaya: datetimeoffset, parameter bernilai tabel, nvarchar, dan Unicode dengan PDO::SQLSRV_ENCODING_UTF8.

Get started

Artikel Deskripsi
Persyaratan sistem Mendukung versi PHP, sistem operasi, dan SQL Server.
Matriks dukungan Matriks kompatibilitas rinci untuk rilis driver PHP.
Unduh Driver Microsoft untuk PHP untuk SQL Server Tautan unduhan dan rilis artefak.
Tutorial instalasi untuk Linux dan macOS Instal driver dan prasyarat ODBC-nya di Linux dan macOS.
Memuat driver Aktifkan ekstensi di php.ini.
Memulai dengan driver PHP SQL Panduan menyeluruh yang menggabungkan keempat langkah memulai.
Gambaran umum driver SQL PHP Apa saja yang ada dalam paket, dan kapan memilih SQLSRV atau PDO_SQLSRV.

Mengonfigurasi dan menyambungkan

Artikel Deskripsi
Menghubungkan ke server Buka koneksi ke instance SQL Server dari PHP.
Opsi koneksi Referensi lengkap untuk kata kunci koneksi, default, dan cara mengaturnya.
Menyambungkan ke Microsoft Azure SQL Database Hubungkan aplikasi PHP ke Azure SQL Database.
Hubungkan pada port tertentu Tentukan port TCP non-default.
Pengumpulan koneksi Gunakan kembali koneksi ODBC di seluruh permintaan PHP.
Nonaktifkan Beberapa Set Hasil Aktif (MARS) Matikan MARS untuk kompatibilitas.
Dukungan untuk LocalDB Hubungkan ke instance SQL Server LocalDB.
Dukungan untuk High Availability, pemulihan dari bencana Pendengar grup ketersediaan dan failover multi-subnet.
Ketahanan koneksi idle Penyambungan ulang otomatis pada koneksi idle yang terputus.

Authenticate

Artikel Deskripsi
Menyambungkan menggunakan autentikasi Microsoft Entra Identitas terkelola, prinsipal layanan, token akses, dan alur kata sandi.
Terhubung menggunakan autentikasi SQL Server Gunakan login SQL dengan nama pengguna dan kata sandi.
Terhubung menggunakan Windows authentication Gunakan autentikasi terintegrasi Windows pada host yang tergabung ke domain.

Secure

Artikel Deskripsi
Pertimbangan keamanan Model ancaman dan panduan pertahanan mendalam untuk aplikasi PHP.
Selalu Terenkripsi dengan driver PHP Mengonfigurasi enkripsi sisi klien untuk kolom sensitif.
Selalu Terenkripsi dengan enklave yang aman Aktifkan beragam operasi pada kolom terenkripsi menggunakan enklave aman.

Ambil dan perbarui data

Artikel Deskripsi
Panduan pemrograman Panduan pemrograman end-to-end untuk kedua driver.
Membandingkan fungsi eksekusi Pilih fungsi eksekusi yang tepat untuk beban kerja Anda.
Eksekusi pernyataan langsung dan pernyataan yang disiapkan (PDO_SQLSRV) Kapan menggunakan eksekusi langsung dibandingkan pernyataan yang sudah dipersiapkan.
Mengambil data Ambil baris, kolom, dan nilai yang di-stream.
Memperbarui data Sisipkan, perbarui, dan hapus baris.
Lakukan kueri yang diparameterisasi Ikat parameter untuk mencegah serangan injeksi SQL.
Kirim data sebagai aliran Stream nilai biner dan karakter besar ke SQL Server.
Melakukan transaksi Kelompokkan pernyataan menjadi transaksi atomik.
Gunakan parameter bernilai tabel Teruskan parameter TABLE ke prosedur tersimpan.
Tentukan tipe kursor dan pilih baris Pilih kursor forward-only, statis, dinamis, atau keyset.

Jenis data

Artikel Deskripsi
Mengonversi tipe data Bagaimana driver memetakan tipe PHP ke tipe SQL Server.
Tipe data bawaan SQL Server Tipe SQL Server default untuk setiap nilai PHP.
Tipe data bawaan PHP Tipe PHP default untuk setiap tipe kolom SQL Server.
Tentukan tipe data SQL Server (SQLSRV) Timpa tipe SQL Server saat mengikat parameter.
Tentukan tipe data PHP Timpa tipe PHP ketika mengambil data.
Kirim dan ambil data UTF-8 Gunakan PDO::SQLSRV_ENCODING_UTF8 untuk konversi bolak-balik Unicode.
Kirim dan ambil data ASCII di Linux dan macOS Tangani konversi pulang-pergi ASCII pada host non-Windows.
Format desimal dan uang (SQLSRV) Format kolom desimal dan uang dengan driver SQLSRV.
Format desimal dan uang (PDO_SQLSRV) Format kolom desimal dan uang dengan driver PDO_SQLSRV.
Pengaturan lokal non-sistem Pemisah desimal lokal dan pertimbangan lokal lainnya.

Kesalahan dan diagnostik

Artikel Deskripsi
Penanganan kesalahan dan peringatan Penanganan kesalahan dan peringatan pada kedua driver.
Konfigurasikan penanganan kesalahan dan peringatan (SQLSRV) Sesuaikan bagaimana driver SQLSRV melaporkan kesalahan dan peringatan.
Menangani kesalahan dan peringatan (SQLSRV) Periksa kesalahan yang dikembalikan oleh fungsi SQLSRV.
Aktivitas pencatatan Aktifkan logging driver untuk pengambilan data diagnostik.

Terapkan dan operasikan

Artikel Deskripsi
Penyesuaian kinerja Manajemen koneksi, batching, pernyataan yang disiapkan, kursor, memori, dan pemantauan sisi server.
Troubleshooting Mendiagnosis masalah umum pada instalasi, koneksi, kueri, tipe data, transaksi, dan kontainer.

Konten referensi

Artikel Deskripsi
Referensi API driver SQLSRV Semua sqlsrv_* fungsi, parameter, dan nilai pengembalian.
Referensi driver PDO_SQLSRV Metode PDO dan PDOStatement yang didukung oleh driver PDO_SQLSRV.
Konstanta Konstanta yang diekspos oleh driver, termasuk konstanta tipe dan pengkodean.
Artikel Deskripsi
Catatan rilis Riwayat per versi dengan fitur baru, perbaikan bug, perubahan dukungan platform, dan tautan unduhan.
Mengenai contoh kode dalam dokumentasi Konvensi yang digunakan oleh contoh kode di bagian ini.
Contoh kode untuk driver SQL PHP Contoh aplikasi end-to-end untuk SQLSRV dan PDO_SQLSRV.
Sumber daya dukungan Saluran komunitas dan dukungan.

Konten terkait

  • Last updated on