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.
Artikel ini mencantumkan komponen yang harus Anda instal di sistem Anda untuk mengakses data dalam SQL Server atau Azure SQL Database menggunakan driver SQLSRV atau PDO_SQLSRV.
Untuk informasi lebih lanjut tentang siklus hidup dukungan dan kebutuhan driver PHP, lihat matriks dukungan. Driver SQLSRV dan PDO_SQLSRV di setiap rilis memiliki persyaratan PHP, sistem operasi, arsitektur, keamanan thread, dan ODBC yang sama.
Bagaimana stack driver saling terhubung
Aplikasi PHP tidak terhubung langsung ke server basis data. Setiap lapisan harus kompatibel dengan lapisan di sebelahnya:
| Lapisan | Apa yang Anda pilih atau konfigurasikan | Seperti apa ketidakcocokan itu |
|---|---|---|
| Application | Fungsi SQLSRV atau kelas dan atribut PDO_SQLSRV | Fungsi yang tidak terdefinisi, driver PDO yang tidak tersedia, atau kesalahan tingkat aplikasi |
| Ekstensi PHP | File SQLSRV dan PDO_SQLSRV yang dibangun untuk versi minor PHP, arsitektur, dan mode keamanan thread | Peringatan startup PHP, kegagalan pemuatan modul, atau crash proses |
| runtime PHP | Konfigurasi antarmuka baris perintah (CLI), modul Apache, PHP-FPM, atau IIS FastCGI | CLI memuat driver tetapi aplikasi web tidak memuat |
| Microsoft ODBC Driver | Versi yang didukung oleh rilis driver PHP yang dipilih | Kegagalan koneksi atau perpustakaan ODBC yang hilang |
| Sistem operasi | Rilis dan arsitektur yang didukung dengan runtime dan paket build yang diperlukan | Tidak ada paket kompatibel, pustaka bersama yang tidak dapat ditemukan, atau kegagalan pembuatan sumber |
| Produk basis data | Target SQL Server atau Azure SQL yang didukung | Kesalahan versi server atau fitur spesifik setelah koneksi terjalin |
SQLSRV dan PDO_SQLSRV menyediakan API PHP yang berbeda melalui driver ODBC yang sama. Instal keduanya saat aplikasi Anda menggunakan kedua API. Menginstal satu ekstensi tidak otomatis menginstal atau mengaktifkan yang lain.
| API | Model pemrograman | Pemeriksaan khusus instalasi |
|---|---|---|
| SQLSRV | Fungsi prosedural sqlsrv_* dan konstanta SQLSRV |
extension_loaded('sqlsrv') dan function_exists('sqlsrv_connect') |
| PDO_SQLSRV | Kelas, atribut, dan pengecualian PHP Data Objects (PDO) |
extension_loaded('pdo_sqlsrv') dan sqlsrv di PDO::getAvailableDrivers() |
Ekstensi dapat dipasang secara independen. PDO_SQLSRV juga mengharuskan PDO dimuat sebelum PDO_SQLSRV.
Pilih set yang kompatibel
Sebelum Anda mengunduh atau membangun driver, selesaikan pemeriksaan berikut:
Identifikasi setiap runtime PHP yang melayani aplikasi tersebut. Tugas terjadwal, pekerja baris perintah, situs IIS, modul Apache, dan pool PHP-FPM dapat menggunakan berbagai executable PHP dan file konfigurasi.
Jalankan perintah berikut dengan setiap executable PHP:
php -i | findstr /I "PHP Version Architecture Thread Safety extension_dir"Di Linux atau macOS, gunakan:
php -i | grep -E "PHP Version|Thread Safety|extension_dir" file "$(php -r 'echo PHP_BINARY;')"Perintah
filetersebut melaporkan arsitektur executable. Jika sistem melaporkan executable universal macOS, pilih arsitektur yang diinginkan secara eksplisit, sepertiarch -arm64 php --versionatauarch -x86_64 php --version. Gunakan pilihan arsitektur yang sama saat membangun, memuat, dan menguji ekstensi.Pilih rilis driver PHP yang mendukung versi minor PHP, sistem operasi, dan target basis data.
Pilih versi Driver Microsoft ODBC yang didukung dari tabel kompatibilitas dalam artikel ini.
Cocokkan file ekstensi atau build PIE dengan arsitektur PHP dan mode thread-safe. Jangan menyalin ekstensi dari instalasi PHP lain kecuali semua nilai ini cocok.
Konfigurasikan dan verifikasi runtime CLI dan server web secara terpisah. Perintah yang berhasil
php -mhanya membuktikan bahwa runtime CLI memuat ekstensi tersebut.
PHP
Unduh biner PHP dari situs web PHP. Pilih versi PHP yang tercantum dalam dukungan versi PHP.
Aktifkan file driver yang sesuai dengan versi PHP Anda. Untuk nama file, lihat Versi Driver. Unduh file dari Download the Microsoft Drivers for PHP for SQL Server. Untuk petunjuk konfigurasi, lihat Muat Driver Microsoft untuk PHP untuk SQL Server.
Pilih server web dan metode integrasi PHP yang didukung oleh PHP dan kerangka kerja aplikasi Anda. Ikuti dokumentasi instalasi PHP dan instruksi deployment framework Anda untuk mengonfigurasi server web agar menjalankan PHP. Verifikasi pemuatan ekstensi di runtime server web secara terpisah dari CLI.
Keamanan thread dan arsitektur
File build dan ekstensi PHP harus sepakat pada kedua nilai tersebut.
| Nilai PHP | Pilihan driver wajib |
|---|---|
Thread Safety => enabled |
File driver Thread-safe (ts atau TS) |
Thread Safety => disabled |
File driver yang tidak aman untuk thread (nts atau NTS) |
Architecture => x64 |
File driver 64-bit dan komponen ODBC 64-bit |
Architecture => x86 |
File driver Windows 32-bit dan komponen ODBC 32-bit |
CLI dapat menggunakan build PHP yang aman untuk thread atau non-thread-aman. Pilih ekstensi berdasarkan nilai yang dilaporkan, bukan dengan mengasumsikan bahwa setiap build CLI tidak aman untuk thread.
pengandar ODBC
Instal Microsoft ODBC Driver untuk SQL Server yang didukung di komputer yang menjalankan PHP. Unduh driver dari Download ODBC Driver for SQL Server.
Jika Anda mengunduh driver versi Windows pada Windows versi 64-bit, penginstal ODBC 64-bit menginstal driver ODBC 32-bit dan 64-bit. Jika Anda menggunakan Windows versi 32-bit, gunakan penginstal ODBC x86. Pada platform non-Windows, hanya driver versi 64-bit yang tersedia.
Tabel ini mencakup kombinasi historis untuk perencanaan peningkatan. Gunakan rilis driver PHP saat ini beserta versi ODBC yang tercantum untuk instalasi baru. Kompatibilitas dengan rilis lama tidak memperpanjang siklus dukungannya. Periksa siklus hidup dukungan driver PHP dan versi yang didukung PHP.
Sel kosong tidak berarti driver PHP tidak selalu menolak versi ODBC tersebut. Fitur individual dapat memerlukan versi ODBC yang lebih baru dibandingkan kombinasi dasar.
| versi driver PHP → ↓ Versi driver ODBC |
5.13 | 5.12 | 5.11 | 5.10 | 5,9 | 5.8 | 5.6 | 5.3 | 5.2 | 4.3 | 4,0 | 3.2 |
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Driver ODBC 18 | Ya | Ya | Ya | Ya | ||||||||
| Driver ODBC 17 | Ya | Ya | Ya | Ya | Ya | Ya | Ya | Ya | Ya | |||
| Driver ODBC 13.1 | Ya | Ya | Ya | Ya | Ya | Ya | Ya | Ya | Ya | Ya | ||
| Driver ODBC 13 | Ya | |||||||||||
| Driver ODBC 11 | Ya | Ya | Ya | Ya | Ya | Ya | Ya |
Jika Anda menggunakan driver SQLSRV, sqlsrv_client_info mengembalikan informasi tentang versi Driver SQL Server Microsoft ODBC untuk SQL Server yang digunakan oleh Driver Microsoft untuk PHP untuk SQL Server. Jika Anda menggunakan driver PDO_SQLSRV, Anda dapat menggunakan PDO::getAttribute untuk menemukan versi.
SQL Server
Untuk versi SQL Server yang didukung, lihat Versi database yang didukung.
Evaluasi dukungan target secara terpisah untuk SQL Server, Azure SQL Database, Azure SQL Managed Instance, Azure Synapse Analytics, database SQL di Microsoft Fabric, dan Warehouse di Microsoft Fabric. Persyaratan instalasi adalah persyaratan sisi klien dan tidak berarti bahwa setiap metode autentikasi, opsi koneksi, fitur Transact-SQL (T-SQL), atau tipe data tersedia di setiap target. Gunakan matriks dukungan dan dokumentasi produk target untuk skenario yang digunakan aplikasi Anda.
Sistem operasi
Untuk sistem operasi yang didukung, lihat Sistem operasi yang didukung.
Versi driver
Setiap rilis Microsoft Driver untuk PHP untuk SQL Server menyertakan file driver SQLSRV dan PDO_SQLSRV dalam varian yang aman untuk thread dan non-aman untuk thread. Di Windows, setiap varian juga dibuat untuk PHP 32-bit dan 64-bit. Cocokkan file driver dengan versi PHP, mode thread-safe/non-thread-safe, dan arsitektur Anda. Untuk mengaktifkan file driver setelah Anda mengunduhnya, lihat Memuat Driver Microsoft untuk PHP untuk SQL Server.
Di Linux dan macOS, instal driver dengan PIE, PHP Installer for Extensions, seperti yang dijelaskan dalam petunjuk instalasi Linux dan macOS. PIE menggantikan sistem paket PHP Extension Community Library (PECL) yang sudah tidak digunakan lagi dan menamai ekstensi yang diinstal sebagai sqlsrv.so atau pdo_sqlsrv.so. Tabel berikut mencantumkan nama file untuk paket biner yang sudah dibangun yang Anda unduh secara manual dari halaman rilis Microsoft Drivers for PHP for SQL Server.
Tabel berikut mencantumkan file dalam paket rilis 5.13. Dalam nama file, ts dan TS berarti thread-safe, dan nts dan NTS berarti non-thread-safe.
Berkas driver Windows
Paket Windows_5.13.xRTW.zip berisi file-file ini.
| File SQLSRV | PDO_SQLSRV file | Versi PHP | Utas aman? | Architecture |
|---|---|---|---|---|
php_sqlsrv_83_nts_x86.dll |
php_pdo_sqlsrv_83_nts_x86.dll |
8.3 | tidak | 32-bit |
php_sqlsrv_83_ts_x86.dll |
php_pdo_sqlsrv_83_ts_x86.dll |
8.3 | ya | 32-bit |
php_sqlsrv_83_nts_x64.dll |
php_pdo_sqlsrv_83_nts_x64.dll |
8.3 | tidak | 64-bit |
php_sqlsrv_83_ts_x64.dll |
php_pdo_sqlsrv_83_ts_x64.dll |
8.3 | ya | 64-bit |
php_sqlsrv_84_nts_x86.dll |
php_pdo_sqlsrv_84_nts_x86.dll |
8.4 | tidak | 32-bit |
php_sqlsrv_84_ts_x86.dll |
php_pdo_sqlsrv_84_ts_x86.dll |
8.4 | ya | 32-bit |
php_sqlsrv_84_nts_x64.dll |
php_pdo_sqlsrv_84_nts_x64.dll |
8.4 | tidak | 64-bit |
php_sqlsrv_84_ts_x64.dll |
php_pdo_sqlsrv_84_ts_x64.dll |
8.4 | ya | 64-bit |
php_sqlsrv_85_nts_x86.dll |
php_pdo_sqlsrv_85_nts_x86.dll |
8.5 | tidak | 32-bit |
php_sqlsrv_85_ts_x86.dll |
php_pdo_sqlsrv_85_ts_x86.dll |
8.5 | ya | 32-bit |
php_sqlsrv_85_nts_x64.dll |
php_pdo_sqlsrv_85_nts_x64.dll |
8.5 | tidak | 64-bit |
php_sqlsrv_85_ts_x64.dll |
php_pdo_sqlsrv_85_ts_x64.dll |
8.5 | ya | 64-bit |
Gunakan file driver non-thread-safe dengan build PHP non-thread-safe, dan file driver thread-safe dengan build PHP thread-safe. Antarmuka baris perintah (CLI) dapat menggunakan salah satu build. Untuk memastikan build yang Anda miliki, jalankan php -i dan periksa nilai Thread Safety.
File driver Linux dan macOS
Paket Mac_5.13.xRTW.tar.gz dan Linux_5.13.xRTW.tar.gz berisi file-file ini. Arsip Linux berisi biner x64, dan arsip macOS berisi biner Arm64.
File prebuilt juga harus sesuai dengan pustaka asli sistem operasi Anda. Biner Linux 5.13.3 memerlukan glibc 2.38 dan versi setelahnya serta runtime C++ yang menyediakan GLIBCXX_3.4.32. Biner macOS 5.13.3 menyatakan macOS 26 sebagai target penyebaran minimum mereka. Persyaratan biner ini terpisah dari dukungan sistem operasi untuk build dari sumber.
Gunakan PIE ketika arsitektur arsip atau kebutuhan perpustakaan asli tidak sesuai dengan instalasi PHP Anda. Build PIE untuk pustaka PHP dan native yang terpasang. Jangan ganti perpustakaan sistem secara manual untuk memuat ekstensi yang telah dikompilasi sebelumnya.
| File SQLSRV | PDO_SQLSRV file | Versi PHP | Utas aman? |
|---|---|---|---|
SQLSRV_8.3_NTS.so |
PDO_SQLSRV_8.3_NTS.so |
8.3 | tidak |
SQLSRV_8.3_TS.so |
PDO_SQLSRV_8.3_TS.so |
8.3 | ya |
SQLSRV_8.4_NTS.so |
PDO_SQLSRV_8.4_NTS.so |
8.4 | tidak |
SQLSRV_8.4_TS.so |
PDO_SQLSRV_8.4_TS.so |
8.4 | ya |
SQLSRV_8.5_NTS.so |
PDO_SQLSRV_8.5_NTS.so |
8.5 | tidak |
SQLSRV_8.5_TS.so |
PDO_SQLSRV_8.5_TS.so |
8.5 | ya |
Salin setiap file yang Anda butuhkan ke direktori ekstensi PHP Anda. Anda dapat mempertahankan nama file paket dan menulis extension=SQLSRV_8.4_NTS.so, atau mengganti nama file menjadi sqlsrv.so dan menulis bentuk extension=sqlsrvsingkat . Terapkan pilihan penamaan yang sama pada PDO_SQLSRV. Untuk menemukan direktori ekstensi, jalankan php -i | grep extension_dir. Ikuti Muat driver di Linux dan macOS untuk mengaktifkan ekstensi dalam file konfigurasi yang benar dan muat PHP Data Objects (PDO) sebelum PDO_SQLSRV.
Rilis sebelumnya
Untuk file driver yang termasuk dalam rilis sebelum 5.13, unduh paket untuk rilis tersebut dari halaman rilis Microsoft Drivers for PHP for SQL Server dan lihat isinya. Rilis sebelum 5.12 menerbitkan paket terpisah untuk setiap sistem operasi dan versi PHP, bukan satu paket per platform.
Verifikasi lingkungan yang dipilih
Jalankan pemeriksaan ini setelah menginstal ekstensi PHP dan driver ODBC, tetapi sebelum mengonfigurasi server web:
php --version
php --ini
php --ri sqlsrv
php --ri pdo_sqlsrv
Dua perintah terakhir harus menampilkan bagian informasi modul yang terpisah. Jika salah satu perintah melaporkan bahwa ekstensi tidak ada, selesaikan prosedur instalasi dan pemuatan platform sebelum menguji koneksi database.
Buat verify-php-drivers.php untuk memeriksa kedua API PHP tanpa memerlukan kredensial:
<?php
$failures = [];
if (!extension_loaded('sqlsrv') || !function_exists('sqlsrv_connect')) {
$failures[] = 'SQLSRV is not loaded.';
}
if (!extension_loaded('pdo_sqlsrv') || !in_array('sqlsrv', PDO::getAvailableDrivers(), true)) {
$failures[] = 'PDO_SQLSRV is not loaded.';
}
echo $failures === []
? "SQLSRV and PDO_SQLSRV are loaded." . PHP_EOL
: implode(PHP_EOL, $failures) . PHP_EOL;
exit($failures === [] ? 0 : 1);
Jalankan dengan executable PHP yang melayani aplikasi:
php verify-php-drivers.php
Output yang diharapkan:
SQLSRV and PDO_SQLSRV are loaded.
Pemeriksaan ini memverifikasi pemuatan ekstensi. Aplikasi ini tidak memverifikasi konektivitas ODBC, autentikasi, kepercayaan sertifikat, akses jaringan, atau izin basis data.
Hapus verify-php-drivers.php setelah Anda mencatat hasilnya.
Diagnosis kegagalan kebutuhan
| Gejala | Kemungkinan pemilik | Periksa |
|---|---|---|
PHP Startup: Unable to load dynamic library |
Pemilihan runtime atau ekstensi PHP | Versi minor PHP, arsitektur, mode keamanan thread, extension_dir, dan nama file yang tepat |
Call to undefined function sqlsrv_connect() |
Konfigurasi ekstensi SQLSRV |
php --ri sqlsrv, file aktif php.ini, dan file yang dipindai .ini |
PDOException: could not find driver |
Ekstensi PDO_SQLSRV atau urutan pemuatan PDO |
php --ri pdo_sqlsrv, PDO::getAvailableDrivers(), dan apakah PDO dimuat terlebih dahulu |
Pustaka msodbcsql atau libodbc tidak ada |
instalasi ODBC atau loader sistem operasi | Paket ODBC, arsitektur, dan dependensi pustaka bersama yang terpasang |
| CLI berhasil tapi situs web gagal | Konfigurasi PHP khusus SAPI | Bandingkan php --ini dengan halaman sementara phpinfo() setelah akses ke halaman diagnostik dibatasi |
| Ekstensi dimuat tetapi koneksi gagal | ODBC, jaringan, autentikasi, sertifikat, atau target basis data | Tangkap koleksi kesalahan SQLSRV atau pengecualian PDO dan lakukan pemecahan masalah pada SQLSTATE yang dilaporkan |