Instal Driver Microsoft untuk PHP di Linux dan macOS

Instruksi ini menginstal PHP, Driver ODBC Microsoft untuk SQL Server, serta ekstensi SQLSRV dan PDO_SQLSRV. Setiap tab menggunakan paket PHP yang disediakan oleh repositori yang menjadi sumber instalasi tab tersebut, sehingga versi dalam perintah berbeda dari satu tab ke tab berikutnya. Ganti dengan versi PHP lain yang tercantum di matriks dukungan jika repositori tersebut menawarkan yang berbeda.

Driver SQLSRV dan PDO_SQLSRV menggunakan dependensi ODBC yang sama dan dapat diinstal secara independen. Instal kedua ekstensi jika aplikasi Anda menggunakan kedua driver.

Pada akhir prosedur, CLI dan runtime server web yang dipilih harus memuat kedua ekstensi, kedua API PHP harus tersedia, dan sampel untuk setiap API harus mengembalikan versi server basis data.

Sebelum Anda mulai

  1. Pilih versi PHP yang didukung oleh rilis driver saat ini dan tersedia untuk rilis sistem operasi Anda.

  2. Tentukan runtime PHP yang Anda butuhkan:

    • CLI untuk skrip, tugas terjadwal, atau pekerja.
    • Modul Apache untuk PHP yang dihosting di Apache.
    • PHP-FPM untuk nginx atau konfigurasi Apache FastCGI.

  3. Konfirmasi arsitektur sistem operasi. Arsip Linux yang dirilis berisi biner x64 dan arsip macOS yang dirilis berisi biner Arm64. PIE melakukan build untuk instalasi PHP di komputer dan merupakan jalur instalasi utama dalam artikel ini.

  4. Instal Driver Microsoft ODBC dan paket pengembangan unixODBC. Paket Microsoft menangani komunikasi basis data. Paket unixODBC menyediakan header yang diperlukan untuk membangun SQLSRV dan PDO_SQLSRV.

  5. Rencanakan untuk memulai ulang setiap server web, pool PHP-FPM, dan proses worker yang berjalan lama setelah menginstal atau mengubah ekstensi.

Manajer paket platform menginstal PHP dan dependensi native. PIE membangun dan menginstal ekstensi PHP. Konfigurasi PHP mengontrol apakah setiap runtime memuatnya. Driver ODBC menangani komunikasi dan enkripsi basis data setelah ekstensi dimuat.

Instal driver dengan PIE

PIE, PHP Installer untuk Ekstensi, adalah installer ekstensi yang didukung untuk rilis driver saat ini. Ini menggantikan alur kerja PHP Extension Community Library (PECL) yang sudah tidak digunakan lagi.

Lengkapi prasyarat platform pada bagian berikut sebelum menginstal driver. Kemudian instal PIE dan setiap driver secara terpisah:

Instal PIE

PIE berjalan di PHP 8.1 dan versi yang lebih baru. Aplikasi ini dapat menginstal ekstensi ke instalasi PHP lain ketika Anda memilih alat pengembangan instalasi tersebut.

Instal curl dan CLI GitHub sebelum melanjutkan. Bagian platform mencakup curl di mana instalasi minimal mungkin tidak menyediakannya.

Unduh arsip PIE PHP (PHAR), dan verifikasi dengan GitHub CLI sebelum menginstal atau menjalankannya:

pie_tmp=$(mktemp -d)
curl -fL --output "$pie_tmp/pie.phar" https://github.com/php/pie/releases/latest/download/pie.phar
gh attestation verify --owner php "$pie_tmp/pie.phar"

Lanjutkan hanya jika verifikasi berhasil:

sudo install -m 755 "$pie_tmp/pie.phar" /usr/local/bin/pie
rm "$pie_tmp/pie.phar"
rmdir "$pie_tmp"
unset pie_tmp

Direktori sementara bersifat privat untuk akun Anda. Jika unduhan atau verifikasi gagal, jangan instal atau jalankan PHAR. Hapus file dan direktori sementara sebelum mencoba lagi.

Pastikan PHAR yang terpasang berjalan dengan executable PHP yang akan Anda gunakan:

php /usr/local/bin/pie --version

Instal driver SQLSRV dan PDO_SQLSRV

Di Linux dan macOS, PIE memeriksa compiler dan alat pengembangan PHP yang dibutuhkan. Instal paket pengembangan platform ODBC dan kompiler C++ sebelum menjalankan PIE. Jalankan PIE dari terminal interaktif. Dapat meminta kata sandi Anda sudo saat membutuhkan izin untuk menginstal file ke direktori sistem.

PIE menggunakan instalasi PHP yang digunakan untuk memanggilnya. Untuk instalasi berversi, tambahkan --with-php-config ke setiap perintah instalasi untuk memilih alat pengembang untuk versi tersebut. Misalnya, gunakan pie install --with-php-config=/usr/bin/php-config8.4 microsoft/sqlsrv ketika alat yang dimaksud adalah /usr/bin/php-config8.4. Terapkan opsi yang sama ke microsoft/pdo_sqlsrv. Alpine menggunakan nama executable berversi; ikuti perintah Alpine alih-alih perintah tanpa versi di bagian ini.

Jalankan satu perintah untuk setiap ekstensi. Perintah-perintah ini menggunakan instalasi PHP default PIE:

pie install microsoft/sqlsrv
pie install microsoft/pdo_sqlsrv

PIE berusaha mengaktifkan setiap ekstensi melalui alat konfigurasi PHP platform atau entri extension= , dan memperingatkan jika tidak bisa. PHP menggunakan antarmuka pemrograman aplikasi server (SAPI) untuk setiap lingkungan eksekusi. Di Debian, Ubuntu, dan SUSE, konfigurasi baris perintah, Apache, dan PHP FastCGI Process Manager (PHP-FPM) dapat berbeda. Instalasi baris perintah yang berhasil tidak mengonfirmasi bahwa server web dapat memuat driver.

Periksa php --ini untuk baris perintah. Sebelum membuat halaman sementara phpinfo() untuk server web, batasi akses halaman diagnostik. Periksa File Konfigurasi yang Dimuat dan .ini file yang dipindai untuk setiap runtime. Jika entri hilang, ikuti Muat driver di Linux dan macOS untuk menambahkannya dalam urutan muat yang benar. Restart server web atau PHP-FPM setelah perubahan konfigurasi. Red Hat biasanya berbagi php.ini di seluruh SAPI, tetapi verifikasi konfigurasi aktif sebelum mengandalkan satu run PIE.

Instalasi pada platform Anda

Pilih konfigurasi sistem operasi dan server web Anda. Selesaikan langkah instalasi di tab tersebut, lalu ikuti Pengujian instalasi Anda.

Pasang di Ubuntu

Nota

Perintah berikut menggunakan repositori PHP packages.sury.org sehingga Anda dapat memilih versi PHP yang didukung. Gunakan instruksi resmi Microsoft untuk menginstal driver ODBC untuk rilis Ubuntu Anda.

Langkah 1. Menginstal PHP (Ubuntu)

sudo apt-get update
sudo apt-get install ca-certificates apt-transport-https curl gnupg2 lsb-release -y
sudo install -d -m 755 /etc/apt/keyrings
sudo curl -fsSL https://packages.sury.org/php/apt.gpg -o /etc/apt/keyrings/php.gpg
sudo chmod 644 /etc/apt/keyrings/php.gpg
echo "deb [signed-by=/etc/apt/keyrings/php.gpg] https://packages.sury.org/php/ $(lsb_release -sc) main" | sudo tee /etc/apt/sources.list.d/php.list
sudo apt-get update
sudo apt-get install php8.4 php8.4-dev php8.4-xml -y

Langkah 2. Menginstal prasyarat (Ubuntu)

Ikuti Menginstal Microsoft ODBC Driver untuk SQL Server di Linux, lalu instal header pengembangan.

sudo apt-get install unixodbc-dev g++ make git -y

Langkah 3. Instal driver PHP untuk Microsoft SQL Server dengan PIE (Ubuntu)

Lakukan instalasi driver dengan PIE dengan menambahkan --with-php-config=/usr/bin/php-config8.4 ke kedua perintah instalasi. Periksa file konfigurasi baris perintah dengan php8.4 --ini.

/usr/local/bin/pie install --with-php-config=/usr/bin/php-config8.4 microsoft/sqlsrv
/usr/local/bin/pie install --with-php-config=/usr/bin/php-config8.4 microsoft/pdo_sqlsrv

Langkah 4. Menginstal Apache dan mengonfigurasi pemuatan driver (Ubuntu)

sudo apt-get install apache2 libapache2-mod-php8.4 -y
sudo a2enmod php8.4

Langkah 5. Mulai ulang Apache dan uji sampel skrip (Ubuntu)

sudo systemctl restart apache2

Untuk menguji penginstalan Anda, lihat Menguji penginstalan Anda di akhir dokumen ini.

Instalasi PECL legacy

PECL sudah usang untuk rilis driver saat ini. Gunakan PIE untuk instalasi baru dan upgrade. Jika deployment yang sudah ada dipin ke PECL, jaga agar versi paketnya selaras dengan runtime PHP dan rencanakan perpindahan ke PIE.

Uji instalasi Anda

Verifikasi runtime baris perintah. Pada Alpine, ganti php dengan php84. Untuk instalasi PHP dengan versi tertentu pada distribusi lain, gunakan executable yang sesuai.

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

Kedua --ri perintah harus mencetak informasi modul yang mencakup ExtensionVer. Daftar modul harus berisi baris sqlsrv dan pdo_sqlsrv yang terpisah.

Sebelum menguji koneksi, pastikan kedua antarmuka API PHP dengan verify-php-drivers.php:

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

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

exit($failed ? 1 : 0);

Output yang diharapkan:

SQLSRV: loaded
PDO_SQLSRV: loaded

Untuk PHP-FPM atau server web, batasi akses halaman diagnostik sebelum membuat halaman sementara phpinfo() . Konfirmasi bagian File Konfigurasi yang Dimuat, extension_dir, dan kedua bagian driver. Restart PHP-FPM atau server web setelah mengubah konfigurasi atau mengganti ekstensi. Hapus halaman setelah verifikasi.

Untuk menguji koneksi live, buat file yang disebut testsql.php di root dokumen sistem Anda. Jalur ini ada /var/www/html di Ubuntu, Debian, dan Red Hat, /srv/www/htdocs di SUSE, /var/www/localhost/htdocs di Alpine, atau $(brew --prefix)/var/www di macOS. Atur SQL_SERVER_NAME, SQL_DATABASE, SQL_UID, dan SQL_PWD variabel lingkungan untuk proses PHP sebelum menjalankan skrip. Jangan hardcode kredensial dalam file di bawah root dokumen.

Untuk pengujian baris perintah, gunakan prompt interaktif untuk mengatur variabel lingkungan tanpa memasukkan kata sandi dalam riwayat shell.

Untuk pengujian modul Apache, pastikan kredensial tidak masuk ke file konfigurasi situs yang umumnya dapat dibaca:

  1. Buat file privat di luar akar dokumen. Gunakan nama file yang tidak digunakan di direktori konfigurasi Apache. Di Linux:

    sudo install -o root -g root -m 600 /dev/null /etc/apache2/php-sql-driver-test.conf

    Pada Red Hat, ganti /etc/apache2 dengan /etc/httpd. Di macOS, buat file sebagai akun yang digunakan untuk menjalankan Apache Homebrew:

    install -m 600 /dev/null "$(brew --prefix)/etc/httpd/php-sql-driver-test.conf"

    Hanya pemilik file dan root yang dapat membaca pengaturan ini. Akun yang memulai Apache harus dapat membaca file tersebut.

  2. Edit file privat di editor teks, dan tambahkan entri berikut:

    SetEnv SQL_SERVER_NAME "tcp:<server>,1433"
SetEnv SQL_DATABASE "<database>"
SetEnv SQL_UID "<user_id>"
SetEnv SQL_PWD "<password>"

    Dalam argumen yang dikutip ganda, tulislah \\ untuk setiap backslash literal dan \" untuk setiap tanda kutip ganda literal. Pertahankan spasi depan dan belakang di dalam tanda kutip. Apache juga mengganti referensi ${NAME}. Jika sebuah nilai berisi urutan tersebut atau pemisah baris, gunakan tes command-line sebagai gantinya. Untuk informasi lebih lanjut, lihat konfigurasi Apache quoting dan escaping.

  3. Di dalam host virtual situs, tambahkan blok Files yang hanya mencakup file privat untuk testsql.php. Jika tidak ada host virtual yang dikonfigurasi, tempatkan blok tersebut dalam konfigurasi server utama. Ganti placeholder dengan path absolut file privat:

    <Files "testsql.php">
    Include "<absolute-path-to-private-file>"
</Files>

  4. Restart Apache. Setelah pengujian, hapus blok Files yang Anda tambahkan, hapus file privat, dan restart Apache lagi. Pertahankan pengaturan situs yang tidak terkait.

PHP-FPM secara default menghapus variabel lingkungan yang diwariskan, dan nginx tidak meneruskan lingkungannya ke PHP-FPM. Gunakan prosedur Ubuntu atau Red Hat berikut hanya dengan layanan PHP-FPM uji terisolasi dan pool. Jangan tambahkan kredensial uji ke layanan atau pool yang menjalankan aplikasi lain: setiap skrip dalam pool tersebut dapat membacanya. Jika Anda menggunakan shared hosting, gunakan tes baris perintah sebagai gantinya.

  1. Buat file milik root di luar root dokumen, seperti /etc/php-sql-driver-test.env, dan batasi akses ke file tersebut:

    sudo touch /etc/php-sql-driver-test.env
sudo chmod 600 /etc/php-sql-driver-test.env

    Tambahkan pengaturan koneksi ke file:

    SQL_SERVER_NAME="tcp:<server>,1433"
SQL_DATABASE="<database>"
SQL_UID="<user_id>"
SQL_PWD="<password>"

    Jaga setiap pengaturan pada satu baris. Di dalam tanda kutip ganda, tulislah \\ untuk setiap backslash literal dan \" untuk setiap tanda kutip ganda literal. Tanda dolar dan backtick tidak dievaluasi sebagai ekspresi shell. Edit file secara langsung daripada menjalankan atau men-source-nya di shell. Untuk informasi lebih lanjut, lihat sintaks EnvironmentFile systemd.

  2. Jalankan sudo systemctl edit php8.4-fpm di Ubuntu atau sudo systemctl edit php-fpm di Red Hat. Tambahkan override systemd ini:

    [Service]
EnvironmentFile=/etc/php-sql-driver-test.env

  3. Tambahkan entri ini ke konfigurasi pool PHP-FPM aktif. Lokasi umum adalah /etc/php/8.4/fpm/pool.d/www.conf di Ubuntu dan /etc/php-fpm.d/www.conf di Red Hat:

    env[SQL_SERVER_NAME] = $SQL_SERVER_NAME
env[SQL_DATABASE] = $SQL_DATABASE
env[SQL_UID] = $SQL_UID
env[SQL_PWD] = $SQL_PWD

  4. Muat ulang systemd dan restart layanan PHP-FPM yang berlaku:

    sudo systemctl daemon-reload
sudo systemctl restart php8.4-fpm

    Pada Red Hat, ganti php8.4-fpm dengan php-fpm.

Setelah pengujian, hapus file lingkungan sementara, entri EnvironmentFile= yang Anda tambahkan, entri kumpulan uji, dan testsql.php. Hapus file override layanan hanya jika Anda membuatnya untuk pengujian ini dan file tersebut tidak berisi pengaturan lain. Pertahankan semua override dan pengaturan pool yang sudah ada. Muat ulang systemd dan restart PHP-FPM lagi setelah menghapus konfigurasi uji.

Contoh SQLSRV

Biarkan nilai variabel lingkungan tetap tidak berubah. Setiap contoh memeriksa apakah pengaturan tidak hilang atau kosong sebelum terhubung. Setiap contoh kemudian menggandakan kurawal penutup dan menambahkan kurawal luar sebelum mengirimkan nama database, nama pengguna, dan kata sandi ke driver. Pengkodean ini mempertahankan kurung literal dan mencegah titik koma memisahkan opsi koneksi.

<?php
$serverName = getenv('SQL_SERVER_NAME');
$databaseName = getenv('SQL_DATABASE');
$uid = getenv('SQL_UID');
$pwd = getenv('SQL_PWD');

if ($serverName === false || $serverName === ''
    || $databaseName === false || $databaseName === ''
    || $uid === false || $uid === ''
    || $pwd === false || $pwd === '') {
    handle_failure("Set SQL_SERVER_NAME, SQL_DATABASE, SQL_UID, and SQL_PWD.");
}

$databaseName = '{' . str_replace('}', '}}', $databaseName) . '}';
$uid = '{' . str_replace('}', '}}', $uid) . '}';
$pwd = '{' . str_replace('}', '}}', $pwd) . '}';
$connectionOptions = array(
    "Database" => $databaseName,
    "UID" => $uid,
    "PWD" => $pwd,
    "Encrypt" => 1,
    "TrustServerCertificate" => 0
);

function handle_failure($message) {
    error_log($message);
    http_response_code(500);
    echo "<h1>Failure</h1>";
    echo "An error occurred. Check the server error log for details.";
    exit(1);
}

function format_errors($errors) {
    $lines = [];
    foreach ($errors as $error) {
        $lines[] = "SQLSTATE: {$error['SQLSTATE']}, code: {$error['code']}, message: {$error['message']}";
    }
    return implode(PHP_EOL, $lines);
}

$conn = sqlsrv_connect($serverName, $connectionOptions);
if ($conn === false) {
    handle_failure(format_errors(sqlsrv_errors()));
}

$tsql = "SELECT @@Version AS SQL_VERSION";

$stmt = sqlsrv_query($conn, $tsql);
if ($stmt === false) {
    handle_failure(format_errors(sqlsrv_errors()));
}

$row = sqlsrv_fetch_array($stmt, SQLSRV_FETCH_ASSOC);
if ($row === null || $row === false) {
    handle_failure("Query returned no rows.");
}

echo "<h1>Success</h1>";
echo htmlspecialchars($row['SQL_VERSION']);

sqlsrv_free_stmt($stmt);
sqlsrv_close($conn);
?>

Contoh penggunaan PDO_SQLSRV

<?php
$serverName = getenv('SQL_SERVER_NAME');
$databaseName = getenv('SQL_DATABASE');
$uid = getenv('SQL_UID');
$pwd = getenv('SQL_PWD');

if ($serverName === false || $serverName === ''
    || $databaseName === false || $databaseName === ''
    || $uid === false || $uid === ''
    || $pwd === false || $pwd === '') {
    handle_failure(new RuntimeException("Set SQL_SERVER_NAME, SQL_DATABASE, SQL_UID, and SQL_PWD."));
}

$databaseName = '{' . str_replace('}', '}}', $databaseName) . '}';
$uid = '{' . str_replace('}', '}}', $uid) . '}';
$pwd = '{' . str_replace('}', '}}', $pwd) . '}';

function handle_failure($exception) {
    error_log($exception->getMessage());
    http_response_code(500);
    echo "<h1>Failure</h1>";
    echo "An error occurred. Check the server error log for details.";
    exit(1);
}

try {
    $conn = new PDO(
        "sqlsrv:server=$serverName;Database=$databaseName;Encrypt=1;TrustServerCertificate=0",
        $uid,
        $pwd
    );
    $conn->setAttribute(PDO::ATTR_ERRMODE, PDO::ERRMODE_EXCEPTION);

    $tsql = "SELECT @@Version AS SQL_VERSION";

    $stmt = $conn->query($tsql);
    $row = $stmt->fetch(PDO::FETCH_ASSOC);
    if ($row === false) {
        throw new RuntimeException("Query returned no rows.");
    }

    echo "<h1>Success</h1>";
    echo htmlspecialchars($row['SQL_VERSION']);
} catch (Throwable $exception) {
    handle_failure($exception);
}

unset($stmt);
unset($conn);
?>

Arahkan browser Anda ke http://localhost/testsql.php (http://localhost:8080/testsql.php di macOS). Koneksi yang berhasil menampilkan string versi server basis data. Kedua contoh menulis detail kesalahan ke log kesalahan PHP. Jika halaman menunjukkan kegagalan, periksa log tersebut.

Untuk membandingkan perilaku baris perintah dan server web, atur variabel lingkungan yang sama untuk terminal Anda dan jalankan:

php testsql.php

Jika menjalankan dari command line berhasil tetapi tidak muncul apa pun di browser Anda, periksa file log Apache. Untuk bantuan lebih lanjut, lihat Sumber daya dukungan untuk driver PHP SQL.

Evaluasi program koneksi 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. Metode autentikasi yang dipilih, opsi koneksi, dan kueri harus didukung oleh target. Instalasi dilakukan di sisi klien. Pemeriksaan ekstensi yang berhasil tidak membuktikan bahwa target menerima kredensial, mempercayai klien, atau mendukung setiap fitur database.

Memecahkan masalah penginstalan

Gejala Layer pemilik Tindakan korektif
PIE tidak dapat menemukan phpize, php-config, atau header Paket pengembangan PHP Instal paket pengembangan untuk versi PHP target dan gunakan opsi --with-php-config yang sesuai
Kompilasi gagal karena compiler C++ hilang Alat build sistem operasi Instal paket compiler platform C++, seperti g++ atau gcc-c++
Tidak dapat menemukan kompilasi sql.h Paket pengembangan ODBC atau jalur compiler Instal unixodbc-dev atau unixODBC-devel; di Apple silicon, atur flag include dan library Homebrew
php --ri mengatakan bahwa ekstensi tidak ada Konfigurasi PHP Periksa php.ini yang dimuat dan direktori pemindaian, tambahkan entri yang benar, lalu mulai ulang proses
PDO laporan could not find driver Pemuatan PDO_SQLSRV atau urutan pemuatan PDO Pastikan PDO dimuat terlebih dahulu dan PDO_SQLSRV menggunakan file konfigurasi yang dipindai kemudian
CLI berfungsi tapi Apache, nginx, atau PHP-FPM gagal Konfigurasi khusus SAPI Bandingkan output CLI dengan phpinfo(), konfigurasikan web SAPI, dan restart web SAPI tersebut
Browser mengembalikan HTTP 502 melalui nginx perutean nginx ke PHP-FPM Periksa fastcgi_pass soket terhadap versi PHP-FPM yang terpasang dan pastikan layanan berjalan
Contoh aplikasi browser melaporkan nilai lingkungan yang hilang Lingkungan server web atau PHP-FPM Konfigurasikan variabel untuk web runtime yang dipilih, lalu restart runtime tersebut
Ekstensi dimuat tetapi koneksi gagal dilakukan ODBC, jaringan, sertifikat, autentikasi, atau produk SQL Baca SQLSTATE dan kesalahan native dari log server; jangan membangun ulang ekstensi kecuali error menunjukkan masalah pemuatan atau kompatibilitas biner

Hapus konfigurasi uji sementara

Setelah verifikasi:

  1. Hapus testsql.php, verify-php-drivers.php, dan halaman sementara phpinfo() apa pun dari root dokumen.

  2. Hapus kredensial sementara dan entri penerusan lingkungan.

  3. Muat ulang service manager saat Anda mengubah override systemd, lalu restart PHP-FPM atau server web.

  4. Simpan entri ekstensi dan paket yang telah diinstal yang dibutuhkan aplikasi.

Konten terkait

  • Terakhir diperbarui pada