Catatan
Akses ke halaman ini memerlukan otorisasi. Anda dapat mencoba masuk atau mengubah direktori.
Akses ke halaman ini memerlukan otorisasi. Anda dapat mencoba mengubah direktori.
Gunakan deklarasi eksplisit untuk mengirim string input sebagai varchar atau nvarchar dengan panjang SQL tertentu. Sebagai alternatif, pilih pengaturan ukuran adaptif untuk memulai dengan panjang yang dipilih dan memperbesar deklarasi saat Anda mengirim nilai yang lebih panjang.
Opsi-opsi ini memerlukan versi 5.14.0 atau lebih baru dan hanya berlaku untuk PDO_SQLSRV, driver PHP Data Objects (PDO). Untuk SQLSRV, lanjutkan menentukan tipe SQL dalam array parameter yang dijelaskan dalam Tentukan tipe data SQL Server. Tidak ada pendekatan yang mengubah definisi kolom tujuan.
Pilih metode deklarasi
| Method | Konfigurasi | Behavior |
|---|---|---|
| Metadata pernyataan eksplisit | Telepon PDOStatement::setAttribute(PDO::SQLSRV_ATTR_PARAM_METADATA, $metadata) setelah prepare. |
Berlaku untuk bindParam, bindValue, dan execute($params). |
| Metadata pengikatan eksplisit | Berikan array deklarasi sebagai argumen kelima dari bindParam. |
Menggantikan seluruh entri metadata pernyataan untuk binding tersebut, termasuk pengkodean opsionalnya. |
| Ukuran adaptif | Atur PDO::SQLSRV_ATTR_DEFAULT_STR_LENGTH pada koneksi sebelum membuat statement. |
Berlaku untuk string input yang memenuhi syarat tanpa deklarasi eksplisit. |
Tanpa metadata eksplisit atau penyesuaian ukuran adaptif, perilaku ukuran parameter yang ada tetap tidak berubah. Anda tidak membutuhkan opsi ini untuk query berparameter biasa.
Deklarasikan string input
Setiap deklarasi adalah array dengan kunci konstanta yang bernilai bilangan bulat dan nilai bilangan bulat.
| Key | Nilai |
|---|---|
PDO::SQLSRV_PARAM_DECLARED_STR_TYPE |
PDO::SQLSRV_PARAM_DECLARED_STR_TYPE_VARCHAR atau PDO::SQLSRV_PARAM_DECLARED_STR_TYPE_NVARCHAR. |
PDO::SQLSRV_PARAM_DECLARED_STR_LENGTH |
Untuk varchar, 1 hingga 8.000 byte. Untuk nvarchar, 1 hingga 4.000 unit kode dalam Format Transformasi Unicode 16-bit (UTF-16). Gunakan PDO::SQLSRV_PARAM_DECLARED_STR_LENGTH_MAX untuk varchar(max) atau nvarchar(max). |
PDO::SQLSRV_ATTR_ENCODING (opsional) |
Pengkodean karakter dari string input PHP. Untuk input dalam Format Transformasi Unicode 8-bit (UTF-8), gunakan PDO::SQLSRV_ENCODING_UTF8 atau PDO::SQLSRV_ENCODING_UTF8_VARCHAR. Tipe yang dideklarasikan, bukan pengkodeannya, menetapkan tipe SQL. Anda juga dapat menggunakan PDO::SQLSRV_ENCODING_SYSTEM untuk input dalam pengkodean sistem. Pengkodean biner tidak didukung. |
Anda harus menyertakan kedua kunci deklarasi. String numerik, nilai Boolean, panjang nol, dan kunci yang tidak dikenali tidak valid. Karakter Unicode tambahan, seperti "\u{1F600}", menempati dua unit kode UTF-16, meskipun PHP menyimpan representasi UTF-8-nya dalam empat byte.
Pengkodean tersebut menggambarkan byte sumber. Tipe yang dideklarasikan menggambarkan parameter SQL yang dikirim ke server. Misalnya, Anda dapat mengirim input UTF-8 sebagai varchar tanpa mengubah byte sumber ke encoding sistem. Konversi ke varchar masih bergantung pada kolasi SQL dan repertoar karakternya. Panjang SQL eksplisit tidak mengalokasikan buffer PHP.
Ketika driver mendeklarasikan parameter bound untuk pernyataan yang disiapkan, driver mengabaikan flag PDO::PARAM_STR_NATL dan PDO::PARAM_STR_CHAR. Gunakan deklarasi untuk memilih varchar atau nvarchar.
Untuk metadata pernyataan, gunakan peta dari pengidentifikasi parameter ke array deklarasi:
- Gunakan posisi berbasis 1 untuk placeholder tanda tanya, seperti
[1 => $declaration]. Posisi harus berupa bilangan bulat dari 1 hingga 2.100 dan harus mengidentifikasi parameter terikat saat Anda mengeksekusinya. - Gunakan nama placeholder unik, dengan atau tanpa titik dua, seperti
['name' => $declaration]atau[':name' => $declaration]. Nama placeholder yang diulang tidak mengidentifikasi posisi unik. Jangan menentukan posisi yang sama dua kali melalui nama atau kunci numerik yang berbeda. - Atur metadata setelah
prepare, bukan di array opsinya. Setiap setter yang berhasil mengganti seluruh peta dan mereset riwayat ukuran adaptif. Penggantian yang tidak valid akan mempertahankan peta sebelumnya. Berikan[]untuk membersihkan peta;nulltidak valid. - Panggil
getAttribute(PDO::SQLSRV_ATTR_PARAM_METADATA)pada pernyataan untuk mengambil peta yang dinormalisasi ke posisi berbasis 1. Ini mengembalikan metadata pernyataan, bukan override per-binding atau riwayat ukuran adaptif.
Array yang diberikan ke execute memberikan nilai, bukan deklarasi. Nilai posisinya menggunakan array PHP berbasis nol yang biasa, seperti ['text']; peta metadatanya masih menggunakan [1 => $declaration].
Untuk bindParam, pertahankan argumen keempat pada 0 untuk deklarasi input. Argumen keempat yang positif menentukan perilaku output buffer; itu bukan panjang deklarasi SQL yang baru. Opsi pengkodean bilangan bulat pada argumen kelima tetap berfungsi. Array deklarasi menimpa seluruh entri pernyataan untuk binding tersebut, sedangkan opsi pengkodean bilangan bulat hanya menimpa pengkodean. Rebinding tanpa array deklarasi menghapus override binding tersebut, tetapi mempertahankan metadata pernyataan.
Contoh: deklarasi eksplisit
Contoh dalam artikel ini mengasumsikan koneksi terbuka PDO di $conn yang menggunakan PDO::ERRMODE_EXCEPTION. Untuk membukanya, lihat Menghubungkan ke server. Mereka menggunakan tabel berikut:
CREATE TABLE dbo.Customers
(
CustomerID int IDENTITY PRIMARY KEY,
Name nvarchar(100) NOT NULL,
Code varchar(10) NOT NULL
);
Tanpa deklarasi, driver mengirimkan setiap nilai string dalam contoh berikut sebagai nvarchar(4000). Setiap contoh mendeklarasikan jenis dan panjang kolom yang cocok.
Contoh berikut menggunakan parameter bernama, metadata pernyataan, dan array yang diberikan ke execute. Server menerima @P1 nvarchar(100) dan @P2 varchar(10).
$stmt = $conn->prepare('INSERT INTO dbo.Customers (Name, Code) VALUES (:name, :code)');
$stmt->setAttribute(PDO::SQLSRV_ATTR_PARAM_METADATA, [
'name' => [
PDO::SQLSRV_PARAM_DECLARED_STR_TYPE => PDO::SQLSRV_PARAM_DECLARED_STR_TYPE_NVARCHAR,
PDO::SQLSRV_PARAM_DECLARED_STR_LENGTH => 100,
],
'code' => [
PDO::SQLSRV_PARAM_DECLARED_STR_TYPE => PDO::SQLSRV_PARAM_DECLARED_STR_TYPE_VARCHAR,
PDO::SQLSRV_PARAM_DECLARED_STR_LENGTH => 10,
],
]);
$stmt->execute(['name' => 'Zoë Martín', 'code' => 'C-1001']);
Contoh berikut menggunakan placeholder tanda tanya dan bindValue untuk menemukan pelanggan dengan kode. Kunci 1 metadata mengidentifikasi placeholder pertama. Deklarasi varchar(10) sesuai dengan kolom Code. Ketika kolom varchar dibandingkan dengan parameter nvarchar, SQL Server mengonversi nilai kolom, yang dapat mencegah pencarian indeks.
$stmt = $conn->prepare('SELECT CustomerID, Name FROM dbo.Customers WHERE Code = ?');
$stmt->setAttribute(PDO::SQLSRV_ATTR_PARAM_METADATA, [
1 => [
PDO::SQLSRV_PARAM_DECLARED_STR_TYPE => PDO::SQLSRV_PARAM_DECLARED_STR_TYPE_VARCHAR,
PDO::SQLSRV_PARAM_DECLARED_STR_LENGTH => 10,
],
]);
$stmt->bindValue(1, 'C-1001', PDO::PARAM_STR);
$stmt->execute();
$customer = $stmt->fetch(PDO::FETCH_ASSOC);
echo $customer['Name'], "\n";
Contoh berikut melewatkan array deklarasi sebagai argumen kelima dari bindParam, dengan 0 sebagai argumen keempat. Panjang yang dinyatakan tetap selama eksekusi. Nilai yang lebih dari 10 karakter gagal dengan SQLSTATE 22001 dan tidak menyisipkan baris apa pun.
$stmt = $conn->prepare('INSERT INTO dbo.Customers (Name, Code) VALUES (?, ?)');
$name = 'Kim Abercrombie';
$code = 'C-1002';
$stmt->bindParam(1, $name, PDO::PARAM_STR, 0, [
PDO::SQLSRV_PARAM_DECLARED_STR_TYPE => PDO::SQLSRV_PARAM_DECLARED_STR_TYPE_NVARCHAR,
PDO::SQLSRV_PARAM_DECLARED_STR_LENGTH => 100,
]);
$stmt->bindParam(2, $code, PDO::PARAM_STR, 0, [
PDO::SQLSRV_PARAM_DECLARED_STR_TYPE => PDO::SQLSRV_PARAM_DECLARED_STR_TYPE_VARCHAR,
PDO::SQLSRV_PARAM_DECLARED_STR_LENGTH => 10,
]);
$stmt->execute();
$name = 'Thomas Hardy';
$code = 'C-100000003';
try {
$stmt->execute();
} catch (PDOException $error) {
if ($error->getCode() !== '22001') {
throw $error;
}
echo "The code is longer than 10 characters.\n";
}
Aktifkan ukuran adaptif
Atur PDO::SQLSRV_ATTR_DEFAULT_STR_LENGTH di array opsi konstruktor koneksi atau dengan PDO::setAttribute. Nilainya harus berupa bilangan bulat dari 0 hingga 8.000. Setelan default, 0, menonaktifkan ukuran adaptif.
Setiap pernyataan baru menyalin pengaturan koneksi. Mengubahnya kemudian memengaruhi statement baru, bukan yang sudah ada. Atribut ini bukanlah pernyataan atau prepare opsi.
Untuk setiap posisi parameter yang memenuhi syarat, driver memulai dari batas minimum yang dikonfigurasi dan memperbesar deklarasi agar sesuai dengan nilai yang lebih panjang. Fitur ini mempertahankan ukuran terbesar yang digunakan pada posisi tersebut saat Anda mengirim nilai yang lebih pendek, kosong, atau null nanti. Untuk input UTF-8 dengan pengkodean default, ini menggunakan nvarchar dan mengukur pertumbuhan dalam unit kode UTF-16. Untuk input yang dikodekan sistem, menggunakan varchar dan menyisihkan tiga byte ekstra untuk setiap byte non-ASCII, karena konversi ke kolasi UTF-8 dapat memperpanjang nilai. Metode ini mempromosikan deklarasi yang melebihi 4.000 unit nvarchar atau 8.000 byte varchar menjadi max, termasuk ketika batas minimum awal melebihi batas tipe tersebut.
Deklarasi eksplisit lebih diutamakan daripada ukuran adaptif. Parameter yang terikat sebagai bilangan bulat, data biner, aliran, atau parameter output/input-output mempertahankan perilaku yang ada. Mengubah tipe SQL yang disimpulkan dengan mengubah pengkodean memulai riwayat ukuran baru untuk parameter tersebut.
Contoh: ukuran adaptif
Contoh berikut menggunakan tabel dari contoh deklarasi eksplisit. Ia menetapkan batas minimum 20 pada koneksi sebelum menyiapkan statement. Eksekusi pertama mengirim @P1 nvarchar(20) dan @P2 nvarchar(20). Nama kedua memiliki 30 karakter, sehingga driver memperbesar @P1 menjadi nvarchar(30). Kedua parameter tersebut nvarchar karena inputnya adalah UTF-8, meskipun kolom Code adalah varchar. Untuk mencocokkan kolom varchar , gunakan deklarasi eksplisit.
$conn->setAttribute(PDO::SQLSRV_ATTR_DEFAULT_STR_LENGTH, 20);
$stmt = $conn->prepare('INSERT INTO dbo.Customers (Name, Code) VALUES (?, ?)');
$stmt->execute(['Ana Trujillo', 'C-1003']);
$stmt->execute(['Hanna Moos-Fernández Bergström', 'C-1004']);
Pengaturan ukuran mengontrol deklarasi parameter, bukan kapasitas kolom tujuan.
Keterbatasan dan kesalahan
- Deklarasi eksplisit hanya mendukung string input dan nilai null yang terikat dengan
PDO::PARAM_STRatauPDO::PARAM_NULL. Mereka menolak pengkodean biner, aliran, jenis parameter lainnya, dan parameter output/input-output. - Pada versi 5.14.0, varchar eksplisit terbatas hanya menerima input American Standard Code for Information Interchange (ASCII). Untuk input non-ASCII, gunakan nvarchar, varchar(max) dengan kolasi yang sesuai, atau ukuran adaptif. Adaptive sizing tidak menghilangkan batasan konversi kolasi.
- Deklarasi eksplisit dan ukuran adaptif tidak didukung dengan Always Encrypted atau emulated prepares. Pengaturan adaptif yang tidak nol membuat pembuatan statement gagal untuk kedua jalur. Nonaktifkan setelan tersebut sebelum membuat statement tersebut. Eksekusi langsung melalui
PDO::SQLSRV_ATTR_DIRECT_QUERYberbeda dari prepared statement yang diemulasikan dan mendukung deklarasi ini. - Metadata tidak valid, jalur deklarasi tidak didukung, dan pengaturan adaptif tidak valid melaporkan SQLSTATE
IMSSP. Sebuah input yang melebihi deklarasi terbatas yang valid melaporkan22001. Tangani kesalahan menurutPDO::ATTR_ERRMODE; contoh mengasumsikan mode pengecualian. - Driver tidak menentukan kolom tujuan atau menulis ulang Transact-SQL Anda untuk memilih deklarasi. Pilih tipe dan panjang yang sesuai dengan skema Anda.