Driver Microsoft untuk PHP dan SQL Server

Unduh driver PHP

Microsoft Drivers untuk PHP untuk SQL Server adalah ekstensi PHP yang dapat Anda gunakan untuk membaca dan menulis data dalam Microsoft SQL Database Engine melalui skrip PHP. Kedua ekstensi menggunakan Driver Microsoft ODBC untuk SQL Server yang sama, tetapi menawarkan API PHP dan opsi khusus driver yang berbeda:

  • SQLSRV mengekspos API prosedural (sqlsrv_*fungsi) yang disesuaikan dengan fitur SQL Server.
  • PDO_SQLSRV mengimplementasikan antarmuka PHP Data Objects (PDO). Anda dapat mempertahankan panggilan PDO dalam kode database yang sudah ada, tetapi tinjau kuerinya dan pengaturan spesifik driver sebelum beralih database.

Kedua driver terhubung ke Azure SQL Database, database SQL di Microsoft Fabric, Azure SQL Managed Instance, dan semua versi serta edisi SQL Server yang didukung, termasuk edisi Express. Kedua driver menerima aliran PHP sebagai parameter input. SQLSRV mendukung pengambilan nilai biner dan karakter besar sebagai aliran. Jangan berasumsi PDO_SQLSRV memiliki perilaku streaming output yang sama.

Pilih titik awal Anda

Garis besar produksi untuk Azure SQL

Contoh PDO_SQLSRV ini membaca server dan basis data dari variabel lingkungan dan terhubung dengan identitas terkelola. Ini membangun nama sumber data (DSN) dan mengaktifkan Transport Layer Security (TLS) dengan validasi sertifikat. Baca nilai-nilai ini dari konfigurasi aplikasi tepercaya, bukan parameter permintaan web. Jalankan program pada host dengan endpoint identitas terkelola setelah memberi identitas akses ke database.

Fungsi pembantu ini dapat melakukan hingga tiga kali percobaan untuk menghubungkan atau menjalankan kueri hanya-baca ketika terjadi kesalahan yang tercantum. Mereka menunggu lebih lama antara percobaan, pola retry yang disebut exponential backoff. Jika kesalahan kueri memerlukan koneksi baru, pembantu kueri akan melemparkan pengecualian untuk ditangani oleh kode pemanggil.

Gunakan versi PHP yang didukung, ekstensi PDO_SQLSRV, dan Microsoft ODBC Driver 18 untuk SQL Server. Untuk nilai autentikasi yang didukung, lihat Hubungkan menggunakan autentikasi Microsoft Entra. Jangan gunakan kembali pembantu kueri untuk transaksi penulisan atau multistatement tanpa merancang kebijakan retry khusus aplikasi: kesalahan tidak selalu memberi tahu Anda apakah operasi penulisan telah dikomit.

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

Gunakan pengaturan ini untuk grup failover Azure SQL Database dan Azure SQL Managed Instance.

  • Driver={ODBC Driver 18 for SQL Server} secara eksplisit memilih ODBC Driver 18 alih-alih mengandalkan penemuan driver. Instal sebelum menjalankan contoh.

  • Atur SQL_DATABASE ke nama database yang sebenarnya. Program ini menggandakan kurawal penutup dan membungkus nama dalam kurawal sebelum memasukkannya ke DSN. Proses escaping menjaga karakter khusus dalam nama agar tidak mengubah cara driver membaca pengaturan koneksi.

  • ConnectRetryCount dan ConnectRetryInterval mengatur ketahanan koneksi menganggur ODBC. Batas waktu kueri pernyataan membatasi pemulihan selama eksekusi. Dengan timeout kueri 30 detik pada sampel, ODBC mungkin berhenti sebelum menghabiskan kelima upaya reconnect. LoginTimeout=90 mengatur pembentukan koneksi, bukan anggaran pemulihan. Helper tingkat aplikasi mencoba ulang error server tertentu; tidak mencoba ulang timeout kueri atau memproses ulang hasil yang diambil sebagian.

  • Aktifkan pencatatan driver bersamaan dengan panggilan error_log() program. Untuk PDO_SQLSRV, set pdo_sqlsrv.log_severity di php.ini atau dengan ini_set() saat runtime. Untuk SQLSRV, konfigurasikan LogSeverity dan LogSubsystems dengan sqlsrv_configure(). 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. Gunakan argumen username konstruktor PDO daripada menyisipkan identitas di DSN. 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 read scale-out atau sekunder yang dapat dibaca, tambahkan ApplicationIntent=ReadOnly ke DSN.

  • Gunakan endpoint yang disediakan oleh layanan SQL Anda, termasuk domain khusus cloud-nya. Selidiki ketidaksesuaian nama sertifikat daripada menonaktifkan validasi sertifikat. Gunakan HostNameInCertificate hanya ketika Anda mengetahui nama sertifikat yang diharapkan untuk endpoint tersebut.

  • ODBC memperoleh token untuk autentikasi identitas terkelola dan autentikasi prinsipal layanan. Dengan AccessToken, aplikasi Anda memperoleh token dan meneruskannya ke driver; ODBC tidak mendapatkannya untuk Anda. Untuk informasi selengkapnya, lihat Menggunakan Microsoft Entra ID dengan Driver ODBC.

  • Simpan informasi koneksi di luar kode Anda. Simpan di sistem konfigurasi aplikasi Anda, dan gunakan Azure Key Vault untuk secret.

  • Dengan SQLSRV, atur opsi koneksi dalam array yang diteruskan ke sqlsrv_connect(). Periksa apakah ada nilai balik false dan periksa sqlsrv_errors() sebelum memutuskan apakah akan mencoba lagi. Atur timeout pernyataan secara terpisah dengan QueryTimeout. Ketahanan koneksi idle menunjukkan rekoneksi ODBC, bukan loop percobaan ulang tingkat aplikasi.

  • 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 PHP: SQLSRV menyediakan fungsi prosedural. PDO_SQLSRV mengimplementasikan PDO. Pasang salah satu ekstensi atau keduanya.
  • 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: Identitas terkelola, prinsipal layanan, dan token akses yang diperoleh secara eksternal melalui Microsoft ODBC Driver for SQL Server yang mendasarinya. Identitas terkelola tanpa kata sandi; ActiveDirectoryServicePrincipal menggunakan rahasia klien.
  • Always Encrypted: Enkripsi kolom sensitif di klien, dengan enklave aman untuk operasi yang didukung pada data terenkripsi.
  • Ketahanan koneksi: Koneksi idle bawaan mencoba ulang dengan ConnectRetryCount dan ConnectRetryInterval.
  • Stream PHP: Kirim nilai biner dan karakter besar dari parameter stream dengan salah satu dari kedua API. Gunakan SQLSRV untuk pengambilan data secara streaming.
  • 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.
Mulai cepat: Menyambungkan dan membuat kueri dengan Microsoft Drivers for PHP Verifikasi ekstensi, konfigurasikan koneksi, dan jalankan query yang diparameterisasi dengan SQLSRV atau PDO_SQLSRV.
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 Ketersediaan Tinggi, 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 di Windows atau Kerberos di Linux dan macOS.

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 Temukan tugas pemrograman untuk kedua pengemudi.
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 Commit atau roll back sekelompok pernyataan bersama-sama.
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 Atur opsi SQLSRV CharacterSet atau atribut PDO_SQLSRV PDO::SQLSRV_ATTR_ENCODING .
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.

Meminta fitur

Untuk mengajukan permintaan fitur, buka issue di repositori GitHub Microsoft Drivers for PHP for SQL Server GitHub repository.