Catatan
Akses ke halaman ini memerlukan otorisasi. Anda dapat mencoba masuk atau mengubah direktori.
Akses ke halaman ini memerlukan otorisasi. Anda dapat mencoba mengubah direktori.
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
- Untuk memverifikasi instalasi Anda dan menjalankan kueri berparameter dengan menggunakan SQLSRV atau PDO_SQLSRV, mulailah dari Quickstart: Menyambungkan dan membuat kueri dengan Microsoft Drivers for PHP.
- Untuk menginstal driver di Linux atau macOS, mulai dengan tutorial Instalasi untuk Linux dan macOS lalu Unduh Driver Microsoft untuk PHP untuk SQL Server.
- Untuk terhubung ke Azure SQL dengan autentikasi tanpa kata sandi, mulailah dengan Menyambung menggunakan autentikasi Microsoft Entra dan Opsi koneksi.
- Untuk membuat aplikasi yang sudah ada tahan terhadap kegagalan sementara, buka Ketahanan koneksi idle.
- Untuk menentukan pilihan antara SQLSRV dan PDO_SQLSRV, buka Gambaran umum Driver Microsoft untuk PHP untuk SQL Server dan Perbandingan fungsi eksekusi.
- Untuk mendiagnosis masalah instalasi, koneksi, atau kueri, buka Troubleshooting, Handling errors and warnings, dan Logging activity.
- Untuk membuat aplikasi yang sudah ada lebih cepat, buka Penyetelan Kinerja.
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_DATABASEke 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.ConnectRetryCountdanConnectRetryIntervalmengatur 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=90mengatur 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, setpdo_sqlsrv.log_severitydiphp.iniatau denganini_set()saat runtime. Untuk SQLSRV, konfigurasikanLogSeveritydanLogSubsystemsdengansqlsrv_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 = 1Untuk 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. Passingnullsebagai pengguna (seperti yang dilakukan sampel) memilih identitas terkelola yang diberikan sistem untuk host Azure. Untuk SQLSRV (prosedural), teruskanUIDdalam array opsi koneksi.Atur
MultiSubnetFailover=truekapan 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=ReadOnlyke DSN.Gunakan endpoint yang disediakan oleh layanan SQL Anda, termasuk domain khusus cloud-nya. Selidiki ketidaksesuaian nama sertifikat daripada menonaktifkan validasi sertifikat. Gunakan
HostNameInCertificatehanya 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 balikfalsedan periksasqlsrv_errors()sebelum memutuskan apakah akan mencoba lagi. Atur timeout pernyataan secara terpisah denganQueryTimeout. Ketahanan koneksi idle menunjukkan rekoneksi ODBC, bukan loop percobaan ulang tingkat aplikasi.Fungsi pembantu percobaan ulang membaca
$e->errorInfo[1]yang dijaga olehisset().PDOException::$errorInfodideklarasikan sebagai?arraydan nilai defaultnya adalahnull, sehingga pemeriksaan defensif menggunakan kode driver0sebagai cadangan dan membiarkan prefiks SQLSTATE08menentukan apakah perlu mencoba lagi.
Untuk informasi selengkapnya tentang setiap bagian konfigurasi ini, lihat:
- Opsi koneksi
- Menyambungkan menggunakan autentikasi Microsoft Entra
- Ketahanan koneksi idle
- Menyambungkan ke Microsoft Azure SQL Database
- Dukungan untuk Ketersediaan Tinggi, pemulihan dari bencana
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 olehTrustServerCertificate. -
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;
ActiveDirectoryServicePrincipalmenggunakan 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
ConnectRetryCountdanConnectRetryInterval. - 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. |
Tugas terkait
| 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.