Muat Driver Microsoft untuk PHP untuk SQL Server

Driver SQLSRV dan PDO_SQLSRV adalah ekstensi PHP. PHP memuatnya saat proses PHP dimulai dengan membaca php.ini dan file tambahan .ini .

Pemuatan terpisah dari penginstalan. Menyalin atau membuat build ekstensi akan menempatkan file di penyimpanan. PHP tidak dapat menggunakan SQLSRV atau PDO_SQLSRV sampai konfigurasi aktif mengandung entri yang benar dan proses PHP dimulai ulang.

Lindungi halaman diagnostik web

Sebelum membuat halaman sementara phpinfo() , konfigurasikan server web agar hanya mengizinkan permintaan localhost atau administrator yang telah diautentikasi. Pertahankan pembatasan itu sampai Anda menghapus halaman tersebut. phpinfo() dapat menampilkan variabel lingkungan, kredensial, dan konfigurasi server. Hapus halaman segera setelah verifikasi selesai.

Pahami cakupan konfigurasi PHP

Setiap antarmuka pemrograman aplikasi server PHP (SAPI) dapat menggunakan executable dan konfigurasi yang berbeda:

Runtime Sumber konfigurasi tipikal Cara mengidentifikasinya
Antarmuka baris perintah (CLI) Direktori pemindaian php.ini yang dilaporkan oleh php --ini Jalankan php --ini dengan file executable yang sama persis
IIS FastCGI Executable PHP yang dikonfigurasi dalam aplikasi IIS FastCGI Gunakan phpinfo() halaman sementara
Modul Apache Konfigurasi modul PHP Apache Gunakan phpinfo() halaman untuk sementara
PHP-FPM Executable FPM, pool, php.ini, dan direktori pemindaian Jalankan biner FPM berversi dengan -i atau gunakan halaman phpinfo() sementara
pekerja yang berjalan lama File eksekusi dan lingkungan yang memulai pekerja Periksa layanan pekerja dan restart layanan pekerja setelah perubahan

Mengubah konfigurasi CLI tidak mengubah IIS, Apache, atau PHP-FPM ketika mereka menggunakan instalasi PHP lain atau direktori pemindaian lain.

Temukan konfigurasi PHP

Jalankan perintah-perintah berikut dengan executable PHP yang digunakan oleh aplikasi Anda:

php --ini
php -i | findstr /I "PHP Version Thread Safety Architecture extension_dir"

Di Linux atau macOS, ganti findstr dengan grep:

php -i | grep -E "PHP Version|Thread Safety|extension_dir"
file "$(php -r 'echo PHP_BINARY;')"

Perintah file ini mengidentifikasi arsitektur executable yang dipilih. Untuk executable macOS universal, ikuti pilihan arsitektur eksplisit.

Nilai File Konfigurasi yang Dimuat dan Pindai file .ini tambahan di mengidentifikasi konfigurasi yang digunakan oleh proses baris perintah. Proses server web atau PHP FastCGI Process Manager (PHP-FPM) mungkin menggunakan file eksekusi PHP atau file konfigurasi yang berbeda. Gunakan halaman sementara phpinfo() untuk mengidentifikasi nilai proses tersebut.

Sebelum mengedit file, catat:

  • Jalur executable PHP dan versinya.
  • php.ini dimuat.
  • Direktori pemindaian tambahan .ini
  • Direktori ekstensi.
  • Mode dan arsitektur thread-safety.
  • Setiap proses yang harus Anda mulai ulang.

Cadangkan setiap file konfigurasi yang Anda ubah.

Instal driver di Windows

Untuk instalasi dengan PHP Installer for Extensions (PIE), pertama-tama unduh dan verifikasi PIE. Jalankan perintah berikut dari direktori yang berisi pie.phar, dengan executable PHP yang seharusnya memuat driver:

php .\pie.phar install microsoft/sqlsrv
php .\pie.phar install microsoft/pdo_sqlsrv

PIE menginstal php_sqlsrv.dll dan php_pdo_sqlsrv.dll. Jika PIE tidak dapat mengaktifkan ekstensi secara otomatis, hapus semua entri SQLSRV dan PDO_SQLSRV yang sudah ada dari php.ini aktif, lalu tambahkan:

extension=php_sqlsrv.dll
extension=php_pdo_sqlsrv.dll

Gunakan hanya satu entri untuk setiap pengemudi. Restart proses PHP setelah mengubah konfigurasinya.

Untuk instalasi ZIP, salin perpustakaan tautan dinamis (DLL) yang sesuai dengan versi minor PHP, arsitektur, dan mode keamanan thread ke dalam extension_dir direktori. Runtime PHP 8.5 x64 thread-safe menggunakan nama file berikut:

php_sqlsrv_85_ts_x64.dll
php_pdo_sqlsrv_85_ts_x64.dll

Tambahkan kedua nama file ke php.ini yang digunakan oleh proses PHP:

extension=php_sqlsrv_85_ts_x64.dll
extension=php_pdo_sqlsrv_85_ts_x64.dll

Ganti 85, ts, dan x64 dengan nilai untuk runtime PHP Anda. Jangan mencampur file thread-safe dan non-thread-safe, file 32-bit dan 64-bit, atau file yang dibuat untuk versi minor PHP lainnya.

Instal driver di Linux dan macOS

Pasang driver menggunakan PIE. Untuk informasi lebih lanjut, lihat tutorial instalasi Linux dan macOS. PIE menginstal file ekstensi dan mencoba mengaktifkannya dengan menggunakan alat konfigurasi PHP platform atau dengan menambahkan entri extension= ke file tambahan .ini atau standar php.ini. Jika PIE melaporkan tidak dapat mengaktifkan ekstensi, tambahkan entri tersebut sendiri dan verifikasi konfigurasi aktif.

Untuk instalasi manual, pilih file .so yang sudah dikompilasi sebelumnya dan sesuai dengan versi PHP, arsitektur, mode keamanan thread, dan pustaka asli sistem operasi Anda. Periksa persyaratan Linux dan macOS prabangun; gunakan PIE jika tidak sesuai dengan lingkungan Anda.

Misalnya, file PHP 8.4 non-thread-safe diberi nama SQLSRV_8.4_NTS.so dan PDO_SQLSRV_8.4_NTS.so. Tempatkan di direktori yang dikembalikan oleh php -i | grep extension_dir. Ganti nama keduanya menjadi sqlsrv.so dan pdo_sqlsrv.so untuk menggunakan entri berikut, atau gunakan nama file paket yang persis di entri tersebut. Tambahkan entri ke konfigurasi PHP aktif Anda sesuai urutan muatan yang dijelaskan di bagian ini:

extension=sqlsrv.so
extension=pdo_sqlsrv.so

PHP Data Objects (PDO) harus dimuat sebelum PDO_SQLSRV. PHP membaca php.ini sebelum memindai file tambahan .ini secara alfabet. Jika distribusi Anda memuat pdo.so dari berkas yang dipindai, tempatkan entri PDO_SQLSRV tersebut ke berkas yang dipindai kemudian, misalnya 30-pdo_sqlsrv.ini saat PDO menggunakan 10-pdo.ini. Jangan letakkan entri PDO_SQLSRV di php.ini dalam kasus tersebut.

Pilih entri ekstensi

Gunakan entri yang sesuai dengan cara driver diinstal:

Platform dan Metode entri SQLSRV item PDO_SQLSRV
Windows dengan PIE extension=php_sqlsrv.dll extension=php_pdo_sqlsrv.dll
ZIP yang dirilis Windows Nama DLL versi tepat, seperti extension=php_sqlsrv_85_ts_x64.dll Nama DLL berversi yang tepat, seperti extension=php_pdo_sqlsrv_85_ts_x64.dll
Linux atau macOS dengan PIE extension=sqlsrv.so extension=pdo_sqlsrv.so
Arsip rilis Linux atau macOS, file yang diganti nama extension=sqlsrv.so extension=pdo_sqlsrv.so
Arsip rilis Linux atau macOS, file asli Nama file arsip yang persis, seperti extension=SQLSRV_8.4_NTS.so Nama file arsip yang persis, seperti extension=PDO_SQLSRV_8.4_NTS.so

Jangan mengonfigurasi baik nama pendek maupun nama berversi untuk ekstensi yang sama. PHP dapat melaporkan bahwa modul sudah dimuat, atau dapat melanjutkan memuat file lama setelah upgrade.

Restart PHP untuk memuat driver

Mulai ulang proses setelah mengubah file ekstensi atau file konfigurasi. Restart server web, PHP-FPM, pekerja antrean, dan proses PHP lama lainnya yang memuat driver.

Ekstensi SQLSRV dan PDO_SQLSRV dapat dimuat secara terpisah, tetapi instal dan verifikasi keduanya saat aplikasi Anda menggunakan kedua driver tersebut. PDO sudah terintegrasi dalam banyak paket PHP. Jika PDO belum terintegrasi, aktifkan ekstensi PDO sebelum PDO_SQLSRV.

Verifikasi driver yang dimuat

Untuk runtime baris perintah, jalankan:

php --ri sqlsrv
php --ri pdo_sqlsrv
php -m | findstr /I "sqlsrv pdo_sqlsrv"

Di Linux atau macOS, gunakan:

php --ri sqlsrv
php --ri pdo_sqlsrv
php -m | grep -E "sqlsrv|pdo_sqlsrv"

Untuk server web, batasi akses halaman diagnostik sebelum membuat halaman sementara yang berisi <?php phpinfo(); ?>. Konfirmasi File Konfigurasi yang Dimuat, extension_dir, serta bagian sqlsrv dan pdo_sqlsrv yang terpisah. Hapus halaman setelah verifikasi.

Juga jalankan pemeriksaan tingkat PHP agar verifikasi mencakup kedua API, bukan hanya nama modul. Simpan program ini sebagai verify-php-drivers.php:

<?php
$checks = [
    'SQLSRV extension' => extension_loaded('sqlsrv'),
    'SQLSRV API' => function_exists('sqlsrv_connect'),
    'PDO_SQLSRV extension' => extension_loaded('pdo_sqlsrv'),
    'PDO_SQLSRV API' => class_exists('PDO')
        && in_array('sqlsrv', PDO::getAvailableDrivers(), true),
];

$failed = false;
foreach ($checks as $name => $passed) {
    echo $name . ': ' . ($passed ? 'loaded' : 'missing') . PHP_EOL;
    $failed = $failed || !$passed;
}

exit($failed ? 1 : 0);

Jalankan program dengan setiap executable PHP yang digunakan aplikasi Anda:

php verify-php-drivers.php

Output yang diharapkan:

SQLSRV extension: loaded
SQLSRV API: loaded
PDO_SQLSRV extension: loaded
PDO_SQLSRV API: loaded

Untuk web runtime, tempatkan file sementara di root dokumen dan akses file tersebut melalui browser. Hapus setelah verifikasi. Program ini tidak membuka koneksi database atau mencetak nilai konfigurasi.

Hapus verify-php-drivers.php setelah Anda menyelesaikan pemeriksaan CLI dan web-runtime.

Mengatasi masalah pemuatan driver

Gejala Menyebabkan untuk memeriksa Tindakan korektif
Unable to load dynamic library Nama file yang salah, extension_dir, versi minor PHP, arsitektur, atau mode keamanan thread yang salah Bandingkan php -i dengan file driver yang dipilih dan gunakan jalur absolut sementara untuk mengisolasi kesalahan jalur
The specified module could not be found pada Windows DLL driver atau salah satu dependensinya tidak tersedia Konfirmasi DLL ada di extension_dir, instal runtime Visual C++ yang cocok, dan periksa ketergantungan DLL yang masih hilang
undefined symbol atau kesalahan shared-library di Linux atau macOS Ketidakcocokan ekstensi dan build PHP, atau ketergantungan ODBC yang hilang Bangun ulang dengan komponen yang dimaksud php-config, lalu periksa pustaka yang dilaporkan hilang
Module "sqlsrv" is already loaded Entri duplikat atau dua file yang dipindai Cari php.ini yang dimuat dan direktori pemindaian, lalu simpan satu entri
could not find driver dari PDO PDO_SQLSRV tidak dimuat, atau PDO dimuat setelahnya Periksa php --ri pdo_sqlsrv dan pindahkan entri PDO_SQLSRV setelah PDO
CLI berfungsi tetapi permintaan web gagal Konfigurasi SAPI yang berbeda atau proses yang tidak di-restart Bandingkan nilai CLI dan phpinfo() konfigurasi, edit konfigurasi web, dan restart proses web
Versi lama ExtensionVer tetap ada setelah pemutakhiran Konfigurasi masih merujuk ke file versi lama Ganti entri lama dengan file yang terpasang oleh metode yang dipilih, hapus duplikat, dan restart semua proses PHP

PHP mengatur penemuan ekstensi dan urutan pemuatan. PIE atau penyalinan manual menyediakan file ekstensi. Loader sistem operasi me-resolve dependensi native. Driver Microsoft ODBC menangani protokol database setelah ekstensi dimuat.

Konten terkait

  • Terakhir diperbarui pada