Membandingkan fungsi eksekusi

Unduh driver PHP

Kedua driver dapat menjalankan pernyataan sekali atau menyiapkan pernyataan untuk eksekusi berulang. Gunakan parameter untuk nilai yang diberikan oleh pengguna, bahkan ketika Anda hanya menjalankan kueri sekali.

Pilih API eksekusi secara terpisah dari cara Anda mengambil hasil. Menyiapkan kueri tidak mengambil baris hasilnya, dan buffering hasil tidak membuat kueri menjadi terparameter. Contoh berikut menyiapkan kueri hanya-baca sekali, eksekusi dua kali dengan nilai berbeda, dan konsumsi setiap hasil sebelum eksekusi berikutnya.

Gaya eksekusi SQLSRV PDO_SQLSRV
Jalankan kueri sekali, tanpa parameter sqlsrv_query PDO::query untuk hasil, atau PDO::exec untuk hitungan baris terpengaruh
Jalankan kueri sekali, dengan parameter sqlsrv_query($conn, $sql, $params) PDO::prepare() diikuti oleh PDOStatement::execute()
Siapkan satu kali, jalankan berulang kali dengan parameter yang berbeda sqlsrv_prepare + sqlsrv_execute PDO::prepare + PDOStatement::execute

sqlsrv_query() menyiapkan dan mengeksekusi dalam satu panggilan serta mengembalikan resource statement. sqlsrv_prepare() mengembalikan sumber daya pernyataan tanpa menjalankannya; panggil sqlsrv_execute() untuk setiap eksekusi. PDO query() mengeksekusi dan mengembalikan PDOStatement, sementara exec() mengembalikan hitungan baris yang terpengaruh, bukan objek hasil. Pemanggilan exec() yang berhasil dapat mengembalikan 0, jadi bandingkan pengembalian kegagalan dengan === false, bukan if (!$count).

PDO::query() tidak menerima array nilai parameter. Argumen opsionalnya mengonfigurasi pengambilan data. Untuk kueri PDO_SQLSRV yang diparameterkan, gunakan prepare() dan execute().

Menyiapkan sekali memungkinkan Anda menggunakan kembali handle pernyataan dengan nilai berbeda. Ini bukan jaminan bahwa server tidak akan pernah mengompilasi ulang rencana eksekusinya. PDO_SQLSRV menggunakan eksekusi yang disiapkan secara default, termasuk untuk PDO::query(); atribut direct-query-nya mengontrol pilihan terpisah tersebut.

Siapkan sekali, jalankan berulang kali

Ini adalah program baris perintah yang terpisah dan lengkap. Instal dan muat ekstensi yang dipilih, lalu atur SQL_SERVER, SQL_DATABASE, SQL_USER, dan SQL_PASSWORD di lingkungan proses PHP. Gunakan database uji SQL Server dan sertifikat server yang dipercaya oleh klien. Untuk pengaturan lingkungan dan alternatif tanpa kata sandi, lihat Menghubungkan ke server.

Simpan nama database, username, dan password yang sebenarnya di variabel environment. Kedua program melakukan escape pada nilai-nilai ini sekali dengan menggandakan kurung kurawal penutup dan membungkus setiap nilai dengan kurung kurawal, sesuai dengan penanganan koneksi bergaya ODBC pada driver PHP. Melakukan escaping pada nilai koneksi merupakan hal yang terpisah dari pengikatan parameter kueri.

Program-program tersebut menjalankan query Transact-SQL (T-SQL) pada dua baris inline tanpa membuat tabel atau mengubah data. Simpan setiap program dalam filenya sendiri .php dan jalankan dengan php <file>. Tidak diperlukan database contoh.

SQLSRV

Teruskan $productId referensi dengan &$productId. Masing-masing sqlsrv_execute() kemudian menggunakan nilainya saat ini. SQLSRV_FETCH_ASSOC mengembalikan array yang diindeks berdasarkan nama kolom. Hasil null berarti tidak ada lagi baris; false menunjukkan kesalahan.

<?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));
}

$sql = "SELECT Name FROM (VALUES (1, 'Bike'), (2, 'Helmet')) AS Product(ProductId, Name) WHERE ProductId = ?";
$productId = 1;
$stmt = null;
try {
    $stmt = sqlsrv_prepare($conn, $sql, [&$productId], ['QueryTimeout' => 30]);
    if ($stmt === false) {
        throw new RuntimeException(print_r(sqlsrv_errors(), true));
    }
    foreach ([1 => 'Bike', 2 => 'Helmet'] as $productId => $expected) {
        if (!sqlsrv_execute($stmt)) {
            throw new RuntimeException(print_r(sqlsrv_errors(), true));
        }
        $names = [];
        while (($row = sqlsrv_fetch_array($stmt, SQLSRV_FETCH_ASSOC)) !== null) {
            if ($row === false) {
                throw new RuntimeException(print_r(sqlsrv_errors(), true));
            }
            $names[] = $row['Name'];
        }
        if ($names !== [$expected]) {
            throw new RuntimeException('Expected exactly one matching product.');
        }
        echo $names[0], PHP_EOL;
    }
} finally {
    if (is_resource($stmt)) {
        sqlsrv_free_stmt($stmt);
    }
    sqlsrv_close($conn);
}

PDO_SQLSRV

Ikatkan $productId sekali dengan bindParam(). Masing-masing execute() menampilkan nilai saat ini. PDO::PARAM_INT menentukan tipe binding PHP/PDO parameter; tipe tersebut tidak mengontrol tipe PHP kolom yang diambil dari hasil. Atur mode pengecualian agar kesalahan basis data menghentikan eksekusi, bukan disalahartikan sebagai hasil kosong.

<?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,
    ]
);
$sql = "SELECT Name FROM (VALUES (1, 'Bike'), (2, 'Helmet')) AS Product(ProductId, Name) WHERE ProductId = ?";
$stmt = null;
try {
    $stmt = $pdo->prepare($sql, [PDO::SQLSRV_ATTR_QUERY_TIMEOUT => 30]);
    $productId = 1;
    $stmt->bindParam(1, $productId, PDO::PARAM_INT);
    foreach ([1 => 'Bike', 2 => 'Helmet'] as $productId => $expected) {
        $stmt->execute();
        $names = $stmt->fetchAll(PDO::FETCH_COLUMN);
        if ($names !== [$expected]) {
            throw new RuntimeException('Expected exactly one matching product.');
        }
        echo $names[0], PHP_EOL;
        $stmt->closeCursor();
    }
} finally {
    $stmt = null;
    $pdo = null;
}

Setiap contoh mencetak:

Bike
Helmet

Nilai dalam array yang diteruskan ke execute() milik PDO diperlakukan sebagai PDO::PARAM_STR. Ketika SQL memerlukan parameter bilangan bulat, seperti hitungan yang diparameterkan TOP , panggil bindValue() dengan PDO::PARAM_INT lalu panggil execute() tanpa array.

Mengikat nilai tanpa mengubah kueri

Penanda parameter mewakili nilai, bukan nama tabel, nama kolom, kata kunci, atau arah pengurutan. Jangan menaruh tanda kutip di sekitar ?. Untuk pengidentifikasi dinamis atau ASC/DESC, pilih dari daftar izin yang dikendalikan aplikasi daripada menggabungkan teks yang tidak dipercaya. Untuk sebuah IN daftar, berikan satu penanda per nilai.

Requirement SQLSRV PDO_SQLSRV
Bind nilai untuk satu eksekusi Berikan array parameter ke sqlsrv_query(). Teruskan array ke execute() setelah prepare(), atau bind nilai terlebih dahulu.
Gunakan kembali nilai saat ini dari variabel Sertakan &$variable dalam array yang diberikan ke sqlsrv_prepare(). Panggil bindParam() dengan variabel, lalu execute() tanpa array. PHP meneruskan variabel secara referensi; jangan tambahkan & di lokasi panggilan.
Mengikat nilai pada saat pengikatan Gunakan nilai dalam array parameter untuk eksekusi. Panggil bindValue(); perubahan selanjutnya pada variabel asli tidak mengubah nilai terikat tersebut.
Tentukan input bilangan bulat Gunakan deskriptor parameter dengan SQLSRV_PARAM_IN, SQLSRV_PHPTYPE_INT, dan SQLSRV_SQLTYPE_INT ketika tipe eksplisit diperlukan. Hubungkan dengan PDO::PARAM_INT. Indeks posisi bindParam() dan bindValue() dimulai dari 1, bukan 0.
Kirim SQL NULL Ikat parameter PHP null, dengan tipe SQL eksplisit saat diperlukan oleh operasi. Ikat dengan PDO::PARAM_NULL.
Terima parameter output Gunakan variabel referensi dengan SQLSRV_PARAM_OUT atau SQLSRV_PARAM_INOUT. Gunakan bindParam() dengan PDO::PARAM_INPUT_OUTPUT serta tipe dan panjang yang diperlukan.

Jaga variabel referensi tetap hidup saat menjalankan pernyataan yang telah disiapkan. Program SQLSRV mengubah variabel terikat daripada menggantikan array parameter. Program PDO sengaja memanggil execute() tanpa array setelah binding; jangan campur pola itu dengan eksekusi berbasis array.

Nilai output dari prosedur tersimpan memerlukan penanganan sendiri, termasuk menyelesaikan pemrosesan hasil prosedur. Jangan menyimpulkan perilaku parameter keluaran dari contoh input saja ini. Untuk informasi lebih lanjut, lihat Menggunakan parameter arah.

Konfigurasikan perilaku eksekusi dan pengambilan

Setting SQLSRV PDO_SQLSRV
Timeout eksekusi QueryTimeout dalam array opsi pernyataan. PDO::SQLSRV_ATTR_QUERY_TIMEOUT pada koneksi atau statement.
Kunci hasil yang dinamai SQLSRV_FETCH_ASSOC diteruskan ke sqlsrv_fetch_array(). PDO::FETCH_ASSOC diteruskan ke metode fetch atau diatur sebagai mode pengambilan default koneksi.
Hasil maju saja kursor bawaan; ambil sesuai urutan. Kursor bawaan; ambil sesuai urutan.
Hasil yang di-buffer oleh klien Scrollable => SQLSRV_CURSOR_CLIENT_BUFFERED. PDO::ATTR_CURSOR => PDO::CURSOR_SCROLL dengan PDO::SQLSRV_ATTR_CURSOR_SCROLL_TYPE => PDO::SQLSRV_CURSOR_BUFFERED.
Eksekusi langsung versus eksekusi yang dipersiapkan Tidak ada atribut PDO direct-query. Pilih panggilan gabungan sqlsrv_query() atau pasangan eksplisit prepare/execute. PDO::SQLSRV_ATTR_DIRECT_QUERY memilih eksekusi langsung versus eksekusi yang sudah dipersiapkan secara default oleh driver.
Emulasi parameter Tidak ada atribut emulasi PDO. PDO::ATTR_EMULATE_PREPARES terpisah dari atribut direct-query. Jangan gunakan sebagai pengganti pengikatan jenis yang benar.

Contoh-contoh tersebut mengembalikan hasil yang kecil. fetchAll() memuat setiap baris ke memori PHP; gunakan loop pengambilan untuk hasil yang besar. Kueri yang tidak mengembalikan kecocokan apa pun bukanlah kesalahan eksekusi. SQLSRV melaporkan akhir hasil sebagai null dari sqlsrv_fetch_array(); PDO melaporkannya sebagai false dari fetch(). Sebuah SQL null dalam baris yang diambil tetap merupakan PHP NULL.

Jangan gunakan hitungan SELECT baris sebagai satu-satunya pemeriksaan keberhasilanmu. Kursor forward-only tidak menyediakan kemampuan jumlah baris yang sama seperti kursor buffer atau scrollable. Ambil dan hitung baris yang Anda butuhkan, atau gunakan kueri terpisah COUNT . Untuk opsi dan batasan khusus kursor, lihat Tentukan tipe kursor dan pilih baris.

Menangani kegagalan dan hasil akhir

Periksa operasi prepare, execute, dan fetch SQLSRV secara terpisah. Prepare yang berhasil tidak membuktikan bahwa eksekusi akan berhasil: server dapat menolak nilai parameter, izin, atau pernyataan saat eksekusi. Tangkap sqlsrv_errors() segera ketika sebuah operasi mengembalikan false. SQLSRV secara default memperlakukan banyak peringatan sebagai kesalahan, jadi periksa seluruh koleksi.

Untuk PDO, kegagalan koneksi dan kesalahan basis data dalam mode pengecualian melempar PDOException. Periksa SQLSTATE dan informasi kesalahan driver dalam diagnostik aplikasi yang dilindungi; jangan kembalikan teks pengecualian atau kredensial dalam respons HTTP. prepare() Berhasil bukanlah bukti bahwa pernyataan itu sudah dijalankan.

Gejala Action
Setiap eksekusi menggunakan nilai pertama Untuk SQLSRV, bind variabel melalui referensi. Untuk PDO, gunakan bindParam() untuk variabel yang berubah atau panggil bindValue() untuk setiap nilai baru.
Parameter numerik ditolak, seperti parameter count TOP Bind tipe bilangan bulat yang diperlukan secara eksplisit. PDO execute([$value]) menggunakan parameter string meskipun nilai PHP-nya adalah bilangan bulat.
Perintah kedua melaporkan hasil tertunda Proses hasilnya atau lepaskan koneksi tersebut sebelum menggunakan kembali koneksi. Untuk PDO, gunakan closeCursor() saat Anda tidak membutuhkan sisa hasilnya.
Parameter output yang diharapkan tidak berubah Lengkapi semua hasil prosedur dan verifikasi arah parameter, tipe PHP, serta panjang buffer output.
Penggunaan memori bertambah seiring dengan ukuran hasil Ganti fetchAll() atau buffering klien yang tidak perlu dengan pengambilan berurutan.

Contoh-contoh tersebut membebaskan statement dan menutup koneksi dalam finally. Mereka tidak memulai transaksi. Gunakan transaksi eksplisit ketika beberapa operasi tulis harus dikomitkan bersama atau semuanya di-rollback. Menggunakan ulang pernyataan yang sudah disiapkan tidak mengelompokkan operasi penulisan tersebut ke dalam transaksi.

Perbedaan target dan implementasi

API prepare/execute dan aturan referensi pada PHP termasuk dalam ekstensi dan PHP/PDO. Target SQL memutuskan pernyataan dan tipe T-SQL mana yang didukung, dan ODBC melakukan komunikasi dasarnya. Melakukan persiapan satu kali dapat mengurangi pekerjaan berulang, tetapi tidak menjamin rencana eksekusi server tertentu atau peningkatan kecepatan.

Pola pengikatan input berlaku untuk SQL Server, Azure SQL Database, Azure SQL Managed Instance, Azure Synapse Analytics, database SQL di Microsoft Fabric, dan Warehouse di Microsoft Fabric. Program-program ini menggunakan autentikasi SQL untuk mengautentikasi ke SQL Server. Untuk onboarding Azure, pilih autentikasi Microsoft Entra. Kedua produk Fabric mewajibkannya, dan Warehouse juga mengharuskan menonaktifkan Multiple Active Result Sets (MARS). Periksa dukungan target yang dipilih untuk perubahan skema, transaksi, dan prosedur tersimpan sebelum menggunakan kembali kode SQL Server. Untuk perbedaan endpoint dan autentikasi, lihat koneksi Azure dan Fabric.