Gambaran umum Driver Microsoft untuk PHP untuk SQL Server

Unduh driver PHP

Driver Microsoft untuk PHP untuk SQL Server mencakup dua ekstensi PHP, SQLSRV dan PDO_SQLSRV. PDO_SQLSRV mengimplementasikan antarmuka PHP Data Objects (PDO). Kedua ekstensi menggunakan Microsoft ODBC Driver for SQL Server untuk terhubung ke Microsoft SQL. API PHP mereka, opsi spesifik driver, dan tipe PHP default berbeda-beda. Misalnya, SQLSRV mengembalikan nilai tanggal dan waktu sebagai DateTime objek secara default, sementara PDO_SQLSRV mengembalikan string secara default. Untuk persyaratan sistem, lihat Persyaratan sistem untuk Microsoft Drivers for PHP for SQL Server.

Pilih SQLSRV atau PDO_SQLSRV

Jika Anda ... Gunakan
Memulai proyek baru tanpa kode PDO di tempat lain? Pilih antarmuka yang akan digunakan aplikasi Anda secara konsisten. SQLSRV menyediakan fungsi prosedural dan deskriptor parameter eksplisit. PDO_SQLSRV cocok dengan kode yang diatur di sekitar objek PDO dan PDOStatement.
Sudah menggunakan PDO dengan database lain (MySQL, PostgreSQL, SQLite) PDO_SQLSRV, sehingga lapisan akses data Anda tetap konsisten di seluruh basis data.
Gunakan framework atau pustaka yang mengharapkan objek koneksi PDO PDO_SQLSRV.
Perlu kontrol manual, potongan demi potongan saat data aliran dikirim SQLSRV, menggunakan sqlsrv_send_stream_data(). PDO_SQLSRV juga mengalirkan nilai besar, dengan mengikat sumber daya aliran PHP dengan PDO::PARAM_LOB, tetapi mengirimkan seluruh aliran secara otomatis selama proses execute() , bukan dalam potongan yang dikendalikan oleh penelepon.
Pelihara aplikasi yang sudah memanggil sqlsrv_* fungsi SQLSRV, kecuali Anda berencana menulis ulang kode akses datanya untuk PDO.

Pasang salah satu ekstensi atau keduanya. Unduhan Windows berisi biner ekstensi terpisah; di Linux dan macOS, instal paket sqlsrv dan pdo_sqlsrv secara terpisah. Anda bisa memuat keduanya dalam proses PHP yang sama. SQLSRV mengembalikan sumber daya koneksi dan pernyataan; PDO_SQLSRV mengembalikan PDO dan PDOStatement objek. Jangan teruskan resource dari satu API ke API lain.

Menggunakan PDO tidak membuat sintaks Transact-SQL (T-SQL) bisa dibawa ke database lain. PDO memberikan Anda antarmuka PHP yang umum; kueri, skema, autentikasi, dan atribut spesifik driver Anda masih dapat bergantung pada Microsoft SQL. Demikian pula, menggunakan ekstensi prosedural tidak memerlukan organisasi prosedural di seluruh aplikasi Anda: Anda dapat memanggil SQLSRV dari kelas kustom Anda sendiri.

Bandingkan hasil yang sama di kedua API

Jalankan program-program ini sebelum memilih representasi PHP yang diharapkan aplikasi Anda. Mereka memilih bilangan bulat, tanggal, dan SQL NULLyang sama, tetapi default-nya tidak identik. Tidak diperlukan tabel atau database contoh.

Instal dan muat ekstensi yang dipilih. Atur SQL_SERVER, SQL_DATABASE, SQL_USER, dan SQL_PASSWORD di lingkungan proses untuk database uji SQL Server yang sudah ada. Sertifikat server harus dipercaya dan sesuai dengan endpoint yang dikonfigurasi. Untuk pengaturan dan alternatif Azure tanpa kata sandi, lihat Menghubungkan ke server.

SQLSRV

Simpan program lengkap ini sebagai compare-sqlsrv.php, dan jalankan php compare-sqlsrv.php.

<?php
$config = [];
foreach (['SQL_SERVER', 'SQL_DATABASE', 'SQL_USER', 'SQL_PASSWORD'] as $name) {
    $value = getenv($name);
    if ($value === false || $value === '') {
        throw new RuntimeException("Set $name before running this example.");
    }
    $config[$name] = $value;
}
foreach (['SQL_DATABASE', 'SQL_USER', 'SQL_PASSWORD'] as $name) {
    $config[$name] = '{' . str_replace('}', '}}', $config[$name]) . '}';
}
$conn = sqlsrv_connect($config['SQL_SERVER'], [
    'Database' => $config['SQL_DATABASE'],
    'UID' => $config['SQL_USER'],
    'PWD' => $config['SQL_PASSWORD'],
    'Encrypt' => true,
    'TrustServerCertificate' => false,
    'LoginTimeout' => 30,
    'CharacterSet' => 'UTF-8',
]);
if ($conn === false) {
    throw new RuntimeException(print_r(sqlsrv_errors(), true));
}
$stmt = null;
try {
    $stmt = sqlsrv_query($conn, "SELECT CAST(42 AS int) AS CountValue, "
        . "CAST('2026-10-19' AS date) AS DayValue, CAST(NULL AS int) AS Missing");
    if ($stmt === false) {
        throw new RuntimeException(print_r(sqlsrv_errors(), true));
    }
    $row = sqlsrv_fetch_array($stmt, SQLSRV_FETCH_ASSOC);
    if ($row === false) {
        throw new RuntimeException(print_r(sqlsrv_errors(), true));
    }
    if (!is_array($row) || $row['CountValue'] !== 42
        || !($row['DayValue'] instanceof DateTime)
        || $row['DayValue']->format('Y-m-d') !== '2026-10-19'
        || $row['Missing'] !== null) {
        throw new RuntimeException('Unexpected SQLSRV values or default types.');
    }
    echo get_debug_type($row['CountValue']), ', ',
        get_debug_type($row['DayValue']), ', ', get_debug_type($row['Missing']), PHP_EOL;
} finally {
    if (is_resource($stmt)) {
        sqlsrv_free_stmt($stmt);
    }
    sqlsrv_close($conn);
}

Output yang diharapkan:

int, DateTime, null

PDO_SQLSRV

Simpan program terpisah ini sebagai compare-pdo.php, dan jalankan php compare-pdo.php. Ini sengaja membiarkan pengambilan angka dan tanggal pada setelan bawaan PDO_SQLSRV.

<?php
$config = [];
foreach (['SQL_SERVER', 'SQL_DATABASE', 'SQL_USER', 'SQL_PASSWORD'] as $name) {
    $value = getenv($name);
    if ($value === false || $value === '') {
        throw new RuntimeException("Set $name before running this example.");
    }
    $config[$name] = $value;
}
foreach (['SQL_DATABASE', 'SQL_USER', 'SQL_PASSWORD'] as $name) {
    $config[$name] = '{' . str_replace('}', '}}', $config[$name]) . '}';
}
$server = $config['SQL_SERVER'];
$database = $config['SQL_DATABASE'];
$pdo = new PDO(
    "sqlsrv:Server=$server;Database=$database;Encrypt=true;"
    . "TrustServerCertificate=false;LoginTimeout=30",
    $config['SQL_USER'],
    $config['SQL_PASSWORD'],
    [
        PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION,
        PDO::SQLSRV_ATTR_ENCODING => PDO::SQLSRV_ENCODING_UTF8,
    ]
);
$stmt = null;
try {
    $stmt = $pdo->query("SELECT CAST(42 AS int) AS CountValue, "
        . "CAST('2026-10-19' AS date) AS DayValue, CAST(NULL AS int) AS Missing");
    $row = $stmt->fetch(PDO::FETCH_ASSOC);
    if ($row !== ['CountValue' => '42', 'DayValue' => '2026-10-19', 'Missing' => null]) {
        throw new RuntimeException('Unexpected PDO_SQLSRV values or default types.');
    }
    echo get_debug_type($row['CountValue']), ', ',
        get_debug_type($row['DayValue']), ', ', get_debug_type($row['Missing']), PHP_EOL;
} finally {
    $stmt = null;
    $pdo = null;
}

Output yang diharapkan:

string, string, null

Kedua program secara eksplisit meminta kunci hasil bernama. Array PHP ini menggunakan nama kolom seperti CountValue, bukan indeks numerik berbasis nol. NULL SQL menjadi PHP null di kedua API. Ini bukan string kosong atau baris hasil yang hilang.

Kedua program membaca nama database, username, dan password yang sebenarnya dari variabel lingkungan. Nilai-nilai ini di-escape satu kali untuk penanganan koneksi gaya ODBC pada driver PHP. Menggandakan kurungan tutup dan memasukkan nilai dalam kurung kurawal mempertahankan karakter khusus; tidak mengganti nama database atau mengubah kata sandi yang disimpan. Untuk informasi lebih lanjut, lihat Menghubungkan ke server.

Contoh akan berhenti saat terjadi kesalahan dan melepaskan sumber daya di finally. SQLSRV melaporkan kegagalan basis data melalui false dan sqlsrv_errors(); PDO_SQLSRV melempar pengecualian untuk kegagalan koneksi dan menggunakan pengecualian untuk kegagalan kueri dengan mode kesalahan yang dikonfigurasi. Dalam aplikasi web, tangkap pengecualian ini dalam kode yang menangani permintaan. Catat detail diagnostik dalam log yang dilindungi alih-alih mengembalikannya ke browser.

Setelah latihan, hapus compare-sqlsrv.php dan compare-pdo.php jika Anda tidak lagi membutuhkannya. Hapus variabel lingkungan kredensial dari proses pengujian setelah selesai.

Pilih jenis, pengkodean, dan penanganan kesalahan

Tentukan jenis PHP yang diharapkan aplikasi Anda, bagaimana ia menangani teks dan error, serta kapan merilis sumber daya basis data.

Keputusan SQLSRV PDO_SQLSRV Dampak pada kode aplikasi
Jenis hasil bilangan bulat Bilangan bulat PHP asli untuk kolom SQL int. String secara default; PDO::SQLSRV_ATTR_FETCHES_NUMERIC_TYPE permintaan yang mendukung tipe PHP numerik. Perbandingan strict dan output terserialisasi bisa berbeda. Jangan berasumsi setiap tipe numerik SQL cocok dengan bilangan bulat atau float PHP.
Hasil tanggal dan waktu DateTime objek secara default; ReturnDatesAsStrings memilih string. String secara bawaan; PDO::SQLSRV_ATTR_FETCHES_DATETIME_TYPE memilih objek. Normalisasi representasi sebelum menserialisasi atau meneruskannya ke kode aplikasi.
Enkoding karakter Atur CharacterSet => 'UTF-8' secara eksplisit. UTF-8 adalah default; konfigurasikan dengan PDO::SQLSRV_ATTR_ENCODING. Jangan transfer opsi SQLSRV ke PDO DSN.
Penanganan kesalahan Periksa false dan segera ambil seluruh kumpulan galat SQLSRV. Konfigurasikan PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION. Baris yang hilang dan kueri yang gagal memerlukan penanganan yang berbeda.
Penggunaan kembali parameter Mengikat variabel secara referensi dalam deskriptor sqlsrv_prepare(). Gunakan bindParam() untuk variabel atau bindValue() untuk nilai saat ini. Penugasan ulang variabel memengaruhi binding referensi, bukan binding nilai sebelumnya.
Cleanup Bebaskan statement, lalu tutup sumber daya koneksi. Referensi pernyataan pelepasan, lalu objek PDO. Sebuah pernyataan dapat menjaga koneksi PDO tetap hidup setelah referensi lain diatur ke null.

Jika Anda memigrasikan aplikasi yang sudah ada, uji perilaku ini dengan nilai representatif sebelum mengubah kode databasenya. Sertakan teks non-ASCII, SQL NULL, tanggal, nilai desimal tepat, dan parameter output prosedur tersimpan. Juga bandingkan bagaimana framework Anda mengonfigurasi atribut PDO. Mengganti nama fungsi saja tidak memigrasikan penanganan kesalahan, binding referensi, atau tipe PHP yang dikembalikan.

Untuk alur kerja tulis dan baca yang sudah berjalan dengan kedua API, gunakan panduan pemrograman. Untuk eksekusi berulang dan input yang dimasukkan secara manual, gunakan fungsi eksekusi kueri Compare.

Ketahui apa yang dilakukan setiap komponen

Pilihan ekstensi Anda mengubah API PHP dan konversi tipenya. Kedua ekstensi menggunakan ODBC untuk berkomunikasi dengan server, mengenkripsi koneksi, dan melakukan autentikasi. Sistem operasi menyediakan sertifikat dan layanan terpercaya seperti Windows authentication atau Kerberos. Target SQL mengontrol izin, skema, dan pernyataan T-SQL yang didukung.

Program perbandingan menggunakan autentikasi SQL untuk SQL Server. Untuk Azure SQL Database, Azure SQL Managed Instance, Azure Synapse Analytics, database SQL di Fabric, atau Warehouse di Fabric, konfigurasikan endpoint layanan dan autentikasi yang didukung sebelum menggunakan kembali pola fetch. Kedua produk Fabric memerlukan autentikasi Microsoft Entra ID; Warehouse juga mengharuskan menonaktifkan beberapa set hasil aktif (MARS). Perbandingan tipe yang berhasil di SQL Server tidak menetapkan bahwa target berbeda mendukung setiap fitur yang tercantum dalam gambaran ini.

Apa yang disediakan oleh kedua ekstensi tersebut

  • Autentikasi terintegrasi, autentikasi SQL, dan autentikasi Microsoft Entra ID, tergantung pada dukungan target. Managed identity tidak menggunakan kata sandi aplikasi; ActiveDirectoryServicePrincipal menggunakan client ID dan client secret. Untuk informasi lebih lanjut, lihat Menghubungkan ke server.
  • Kueri yang diparameterkan, prepared statement, dan parameter arah (input/output). Untuk informasi lebih lanjut, lihat Membandingkan fungsi eksekusi dan Menggunakan parameter arah.
  • Transaksi, parameter input aliran untuk nilai karakter besar dan biner, serta parameter bernilai tabel.
  • Selalu Terenkripsi, termasuk enclave aman di mana driver ODBC dan target SQL Server mendukungnya. Untuk informasi lebih lanjut, lihat Menggunakan Selalu Terenkripsi dengan Microsoft Drivers untuk PHP for SQL Server.
  • Koneksi ke SQL Server, Azure SQL Database, Azure SQL Managed Instance, Azure Synapse Analytics, database SQL di Microsoft Fabric, dan Warehouse di Microsoft Fabric. Fitur autentikasi dan SQL bervariasi menurut target; lihat koneksi Azure dan Fabric.