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.
Setelah Anda memiliki koneksi yang berfungsi dari Getting started, gunakan panduan ini untuk menulis, mengkomit, dan membaca baris dengan salah satu API PHP. Setiap program memiliki penyiapan dan pembersihan sendiri. Gunakan tautan tugas untuk memperluas alur kerja daripada menyalin opsi dari satu API ke API lain.
Siapkan koneksi uji coba
Gunakan database uji SQL Server yang sudah ada dan login yang dapat terhubung serta membuat tabel sementara lokal. Contoh-contoh tersebut menggunakan autentikasi SQL. Untuk pilihan autentikasi yang didukung dan onboarding Azure tanpa kata sandi, lihat Menghubungkan ke server.
Muat ekstensi yang Anda pilih, lalu atur SQL_SERVER, SQL_DATABASE, SQL_USER, dan SQL_PASSWORD di lingkungan proses PHP.
SQL_SERVER dapat menyertakan port eksplisit, seperti <server>,1433. Server harus menampilkan sertifikat yang dipercaya oleh klien dan valid untuk endpoint tersebut. Simpan kata sandi di luar program dan kontrol versi.
Simpan nama database, username, dan password yang sebenarnya di variabel environment. Setiap program menggandakan kurungan penutup dan memasukkan nilai-nilai ini ke dalam kurung kurawal sekali untuk penanganan koneksi gaya ODBC pada driver PHP. Melakukan escape mempertahankan karakter khusus dalam nilai koneksi; ini bukan parameterisasi kueri. Untuk informasi lebih lanjut, lihat Menghubungkan ke server.
Pernyataan Transact-SQL (T-SQL) membuat #PhpGuide, sebuah tabel sementara yang hanya terlihat oleh koneksi yang membuatnya. Program-program tersebut tidak membuat atau mengubah tabel aplikasi permanen. Pertahankan koneksi yang sama sepanjang alur kerja.
Tulis dan baca satu baris
Program-program ini menyisipkan integer, teks UTF-8, dan SQL NULL melalui parameter. Mereka mengharuskan tepat satu baris terpengaruh, melakukan commit transaksi, dan memverifikasi nilai serta tipe PHP yang dikembalikan. Kueri terakhir juga memeriksa bahwa tidak ada transaksi yang tetap terbuka.
SQLSRV
Simpan program lengkap ini sebagai workflow-sqlsrv.php, dan jalankan php workflow-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;
$inTransaction = false;
$failure = null;
try {
$stmt = sqlsrv_query($conn, 'CREATE TABLE #PhpGuide '
. '(Id int PRIMARY KEY, Title nvarchar(80), OptionalCount int NULL)');
if ($stmt === false) {
throw new RuntimeException(print_r(sqlsrv_errors(), true));
}
sqlsrv_free_stmt($stmt);
$stmt = null;
if (!sqlsrv_begin_transaction($conn)) {
throw new RuntimeException(print_r(sqlsrv_errors(), true));
}
$inTransaction = true;
$id = 1;
$title = "Caf\u{00E9}";
$optionalCount = null;
$params = [
[&$id, SQLSRV_PARAM_IN, SQLSRV_PHPTYPE_INT, SQLSRV_SQLTYPE_INT],
[&$title, SQLSRV_PARAM_IN, SQLSRV_PHPTYPE_STRING('UTF-8'), SQLSRV_SQLTYPE_NVARCHAR(80)],
[&$optionalCount, SQLSRV_PARAM_IN, SQLSRV_PHPTYPE_INT, SQLSRV_SQLTYPE_INT],
];
$stmt = sqlsrv_prepare($conn,
'INSERT INTO #PhpGuide (Id, Title, OptionalCount) VALUES (?, ?, ?)', $params);
if ($stmt === false || !sqlsrv_execute($stmt)) {
throw new RuntimeException(print_r(sqlsrv_errors(), true));
}
$affected = sqlsrv_rows_affected($stmt);
if ($affected === false) {
throw new RuntimeException(print_r(sqlsrv_errors(), true));
}
if ($affected !== 1) {
throw new RuntimeException('Expected exactly one inserted row.');
}
sqlsrv_free_stmt($stmt);
$stmt = null;
if (!sqlsrv_commit($conn)) {
throw new RuntimeException(print_r(sqlsrv_errors(), true));
}
$inTransaction = false;
$stmt = sqlsrv_query($conn,
'SELECT Id, Title, OptionalCount, @@TRANCOUNT AS TransactionCount FROM #PhpGuide');
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 ($row !== ['Id' => 1, 'Title' => $title, 'OptionalCount' => null, 'TransactionCount' => 0]) {
throw new RuntimeException('Unexpected committed values, types, or transaction state.');
}
$end = sqlsrv_fetch_array($stmt, SQLSRV_FETCH_ASSOC);
if ($end === false) {
throw new RuntimeException(print_r(sqlsrv_errors(), true));
}
if ($end !== null) {
throw new RuntimeException('Expected exactly one result row.');
}
} catch (Throwable $error) {
$failure = $error;
if ($inTransaction && !sqlsrv_rollback($conn)) {
$failure = new RuntimeException(
'Rollback failed: ' . print_r(sqlsrv_errors(), true), 0, $error);
}
throw $failure;
} finally {
if (is_resource($stmt)) {
sqlsrv_free_stmt($stmt);
}
try {
$cleanup = sqlsrv_query($conn, 'DROP TABLE IF EXISTS #PhpGuide');
if ($cleanup === false) {
throw new RuntimeException(
'Cleanup failed: ' . print_r(sqlsrv_errors(), true), 0, $failure);
}
sqlsrv_free_stmt($cleanup);
} finally {
sqlsrv_close($conn);
}
}
echo "Inserted 1 row; read committed UTF-8 text and null; no open transaction.", PHP_EOL;
PDO_SQLSRV
Simpan program terpisah ini sebagai workflow-pdo.php, dan jalankan php workflow-pdo.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]) . '}';
}
$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,
PDO::SQLSRV_ATTR_FETCHES_NUMERIC_TYPE => true,
]
);
$stmt = null;
$failure = null;
try {
$pdo->exec('CREATE TABLE #PhpGuide '
. '(Id int PRIMARY KEY, Title nvarchar(80), OptionalCount int NULL)');
$pdo->beginTransaction();
$title = "Caf\u{00E9}";
$stmt = $pdo->prepare(
'INSERT INTO #PhpGuide (Id, Title, OptionalCount) VALUES (?, ?, ?)');
$stmt->bindValue(1, 1, PDO::PARAM_INT);
$stmt->bindValue(2, $title, PDO::PARAM_STR);
$stmt->bindValue(3, null, PDO::PARAM_NULL);
$stmt->execute();
if ($stmt->rowCount() !== 1) {
throw new RuntimeException('Expected exactly one inserted row.');
}
$stmt = null;
$pdo->commit();
$stmt = $pdo->query(
'SELECT Id, Title, OptionalCount, @@TRANCOUNT AS TransactionCount FROM #PhpGuide');
$row = $stmt->fetch(PDO::FETCH_ASSOC);
if ($row !== ['Id' => 1, 'Title' => $title, 'OptionalCount' => null, 'TransactionCount' => 0]) {
throw new RuntimeException('Unexpected committed values, types, or transaction state.');
}
if ($stmt->fetch(PDO::FETCH_ASSOC) !== false || $pdo->inTransaction()) {
throw new RuntimeException('Expected one result row and no open transaction.');
}
} catch (Throwable $error) {
$failure = $error;
if ($pdo->inTransaction()) {
try {
$pdo->rollBack();
} catch (PDOException $rollbackError) {
$failure = new RuntimeException(
'Rollback failed: ' . $rollbackError->getMessage(), 0, $error);
}
}
throw $failure;
} finally {
$stmt = null;
try {
$pdo->exec('DROP TABLE IF EXISTS #PhpGuide');
} catch (PDOException $cleanupError) {
throw new RuntimeException(
'Cleanup failed: ' . $cleanupError->getMessage(), 0, $failure ?? $cleanupError);
} finally {
$pdo = null;
}
}
echo "Inserted 1 row; read committed UTF-8 text and null; no open transaction.", PHP_EOL;
Output yang diharapkan untuk kedua program:
Inserted 1 row; read committed UTF-8 text and null; no open transaction.
Output hanya muncul setelah pemeriksaan dan pembersihan berhasil. Kegagalan koneksi, tulis, pengambilan, rollback, atau pembersihan tabel justru menimbulkan pengecualian.
Pahami pilihan yang ada
Gunakan ? placeholder untuk nilai daripada menggabungkan input ke dalam T-SQL. Contoh-contoh tersebut mempertahankan nama tabel dan kolom tetap tetap: parameter nilai tidak dapat menggantikan pengenal. Pernyataan yang disiapkan juga memungkinkan Anda mengeksekusi pernyataan yang sama lagi dengan nilai yang berbeda. Untuk informasi lebih lanjut, lihat Bandingkan fungsi eksekusi query.
| Pilihan | Alasan |
|---|---|
| Metode transaksi eksplisit | Contoh memperlakukan penulisan sebagai unit yang harus di-commit atau di-roll back. SQLSRV menggunakan sqlsrv_begin_transaction, sqlsrv_commit, dan sqlsrv_rollback; PDO menggunakan metode transaksi sendiri. |
| Deskriptor parameter SQLSRV | Setiap deskriptor menentukan arah, tipe PHP, dan tipe SQL. Referensi mempertahankan variabel input, termasuk variabel yang berisi null. |
PDO bindValue |
Pernyataan menerima setiap nilai yang ada saat ini dengan tipe parameter PDO yang eksplisit.
bindParam sesuai ketika eksekusi berikutnya harus membaca variabel melalui referensi. |
| UTF-8 plus nvarchar | PHP menyediakan UTF-8 byte; ekstensi dan driver ODBC mengonversinya untuk kolom SQL Unicode. Teks yang diambil harus sesuai dengan string PHP asli byte untuk byte. |
| Pengambilan numerik eksplisit untuk PDO | Perbandingan hasil memerlukan bilangan bulat PHP. Tanpa atribut PDO_SQLSRV, hasil bilangan bulat SQL ini menggunakan representasi string default dari driver. |
| Kunci fetch bernama |
SQLSRV_FETCH_ASSOC dan PDO::FETCH_ASSOC mengembalikan array yang diindeks berdasarkan nama kolom. Konstanta API tidak bisa dipertukarkan. |
PDO::exec untuk pengaturan tabel |
Langsung menjalankan statement pembuatan tabel. Pendekatan ini menghindari pembuatan tabel sementara dalam lingkup pernyataan yang disiapkan server. |
| Hasil maju-saja | Program-program membaca setiap baris satu kali. Mereka tidak meminta hasil yang dibuffer atau menggunakan hitungan baris SELECT sebagai bukti bahwa pengambilan berhasil. |
SQLSRV kembali null saat pengambilan array mencapai akhir dan false terjadi kesalahan pengambilan barang. Pengambilan PDO kembali false di akhir; dengan mode pengecualian dikonfigurasi, kesalahan pengambilan basis data akan muncul. Di kedua API, field OptionalCount itu sendiri berisi PHP null. Nilai kolom itu bukan penanda akhir hasil pencarian.
Operasi tulis melakukan commit sebelum kueri verifikasi. Jika pembacaan yang dilakukan selanjutnya gagal, tulisan yang telah dikomitmenkan sebelumnya tidak dapat dikembalikan. Dalam contoh ini, baris hanya milik tabel sementara yang dihapus oleh proses pembersihan. Dalam aplikasi dengan tabel permanen, laporkan kegagalan secara akurat dan jangan mengulangi sisipan secara membabi tahu setelah hasil commit yang tidak pasti.
Menangani kegagalan dan pembersihan
Blok tersebut catch membatalkan transaksi aktif dan melempar kembali kegagalan tersebut. Blok akan finally melepaskan pernyataan, menghapus tabel sementara, dan melepaskan koneksi. Pembersihan berjalan di jalur keberhasilan dan jalur kegagalan. Jika rollback atau pembersihan tabel juga gagal, program mempertahankan exception asli sebagai exception sebelumnya.
Untuk latihan baris perintah, pengecualian yang tidak tertangkap menghentikan PHP dengan kode keluar yang tidak nol dan pesan kesalahan. Di aplikasi web, tangkap dalam kode yang menangani permintaan. Hapus nilai sensitif sebelum mencatat diagnostik di log aplikasi Anda, dan kembalikan respons kesalahan yang sesuai. Jangan menampilkan detail koneksi, kredensial, atau kesalahan database mentah ke browser.
| Failure | Apa yang harus diperiksa |
|---|---|
| Fungsi ekstensi atau driver hilang | Konfirmasi proses PHP memuat ekstensi yang diinginkan dengan runtime dan konfigurasi yang sesuai. Konfigurasi PHP baris perintah yang berfungsi tidak membuktikan server web Anda menggunakannya. |
| Kegagalan koneksi atau sertifikat | Periksa endpoint, autentikasi, izin, dan kepercayaan sertifikat klien sebelum mengubah kode kueri. Jangan nonaktifkan validasi sertifikat sebagai solusi untuk lingkungan produksi. |
| Tabel sementara tidak ditemukan | Tetap setup, write, dan read pada satu koneksi. Untuk pengaturan PDO, pertahankan path yang ditunjukkan exec daripada menggantikan panggilan prepared query default. |
| Nilai tak terduga atau tipe PHP | Periksa atribut pengambilan dan deskriptor parameter. Jangan ganti assertion ketat dengan loose comparison untuk menyembunyikan perbedaannya. |
| Kegagalan menulis atau rollback | Tangkap kesalahan SQLSRV segera, atau tangkap exception PDO. Laporkan juga kegagalan rollback; jangan klaim penulisan dibatalkan jika rollback gagal. |
| Kegagalan pembersihan setelah kehilangan koneksi | Program tidak dapat mengonfirmasi koneksi terputus di sisi server. Melepaskan handle PHP tidak membuktikan koneksi fisik pooled yang mendasarinya langsung tertutup. |
Ekstensi PHP menyediakan API pengikatan dan pengambilan (pickch) API. ODBC berkomunikasi dengan server dan mengelola connection pooling. SQL Server mengontrol cakupan tabel sementara, transaksi, batasan, dan data yang dikomitmen. Hapus tabel secara eksplisit daripada mengandalkan penutupan koneksi fisik untuk pembersihan.
Setelah latihan, hapus workflow-sqlsrv.php dan workflow-pdo.php jika Anda tidak lagi membutuhkannya. Hapus variabel lingkungan kredensial dari proses pengujian setelah selesai. Tidak ada satu pun program yang membuat tabel permanen untuk dihapus.
Walkthrough ini menargetkan SQL Server. Untuk Azure SQL Database, Azure SQL Managed Instance, Azure Synapse Analytics, database SQL di Fabric, dan Warehouse di Fabric, pertama-tama periksa metode autentikasi pada target dan dukungan T-SQL. Kedua produk Fabric memerlukan autentikasi Microsoft Entra ID, dan Warehouse mengharuskan multiple active result sets (MARS) dinonaktifkan. Program SQL Server ini tidak mendukung dukungan untuk transaksi khusus layanan atau tabel sementara.
Pilih tugas Anda berikutnya
Perluas alur kerja dengan komponen sesuai perilaku yang Anda butuhkan.
| Tugas | Guidance |
|---|---|
| Pilih autentikasi atau kelola koneksi | Menghubungkan ke server. |
| Gunakan kembali prepared statement dengan nilai berbeda | Bandingkan fungsi eksekusi kueri. |
| Pilih PDO langsung atau eksekusi yang dipersiapkan | Eksekusi pernyataan langsung dan eksekusi pernyataan yang disiapkan di driver PDO_SQLSRV. |
| Ambil data dan pilih format hasil | Memuat data. |
| Gulir atau simpan hasil ke buffer | Menentukan tipe kursor dan memilih baris. |
| Ubah data aplikasi | Memperbarui data. |
| Kontrol konversi tipe PHP dan SQL | Mengonversi tipe data. |
| Diagnosis kegagalan dan aktifkan pencatatan driver | Menangani kesalahan dan peringatan serta pencatatan aktivitas. |
| Lindungi kolom sensitif | Menggunakan Always Encrypted dengan Driver Microsoft untuk PHP untuk SQL Server. |
| Mengamankan aplikasi produksi | Pertimbangan keamanan untuk Microsoft Drivers for PHP for SQL Server. |