Persyaratan sistem untuk Driver Microsoft untuk PHP untuk SQL Server

Unduh driver PHP

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:

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

  2. 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 file tersebut melaporkan arsitektur executable. Jika sistem melaporkan executable universal macOS, pilih arsitektur yang diinginkan secara eksplisit, seperti arch -arm64 php --version atau arch -x86_64 php --version. Gunakan pilihan arsitektur yang sama saat membangun, memuat, dan menguji ekstensi.

  3. Pilih rilis driver PHP yang mendukung versi minor PHP, sistem operasi, dan target basis data.

  4. Pilih versi Driver Microsoft ODBC yang didukung dari tabel kompatibilitas dalam artikel ini.

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

  6. Konfigurasikan dan verifikasi runtime CLI dan server web secara terpisah. Perintah yang berhasil php -m hanya membuktikan bahwa runtime CLI memuat ekstensi tersebut.

PHP

Unduh biner PHP dari situs web PHP. Pilih versi PHP yang tercantum dalam dukungan versi PHP.

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