使用本指南開啟連線,驗證 PHP 收到的值,並在工作完成後釋放連線。 這些程式針對本機或遠端的 SQL Server 測試資料庫使用 SQL Server 驗證。 對於無密碼的 Azure 和 Fabric 連線,請使用 連線到 Azure SQL 和 Fabric SQL。
SQLSRV 接受伺服器名稱及關聯陣列的連線選項。 PDO_SQLSRV實作 PHP 資料物件(PDO),並接受資料來源名稱(DSN)字串、獨立的認證參數,以及一組 PDO 屬性陣列。 兩者都使用 Microsoft ODBC Driver for SQL Server。 一個可與某個 API 搭配運作的連線,並不會讓另一個 API 的選項名稱或 PHP 類型可以互換。
連線前
- 安裝支援的 PHP 執行環境和 Microsoft ODBC 驅動程式,然後載入你打算使用的 PHP 擴充功能。
- 檢查執行你應用程式的 PHP 程序。 執行
php --ini以查找命令列設定並php -m列出已載入的擴充功能。 SQLSRV 需要sqlsrv。 PDO_SQLSRV 需要PDO和pdo_sqlsrv。 Web 伺服器可以使用與終端機不同的php.ini、執行時和帳號。 - 取得伺服器地址、資料庫名稱及具有連線權限的身分。 資料庫登入帳號不會自動授權每個資料表。
- 設定網路存取權限和受信任的伺服器憑證。 這些程式會明確要求加密與憑證驗證。 請依憑證上的主機名稱連接,而不要以憑證未涵蓋的 IP 位址取代該主機名稱。
在 PHP 行程的環境中,使用你的 shell、開發工具或主機設定來設定這些變數。 不要提交密碼檔或輸出環境變數。
| 變數 | Value |
|---|---|
SQL_SERVER |
伺服器主機名稱,可選擇以 tcp: 為前綴,後接 ,<port>。 |
SQL_DATABASE |
一個現有的資料庫,您的登入帳號可以存取。 |
SQL_USER |
一個 SQL Server 登入帳戶。 |
SQL_PASSWORD |
該登入帳號的密碼,透過受保護設定提供。 |
讀取伺服器和資料庫設定時,是從受信任的應用程式設定中取得,而非網頁請求參數。 PDO 範例中將這些設定放在 DSN 中。 保持其連線關鍵字在應用程式控制之下。
將實際的資料庫名稱、使用者名稱和密碼存入環境變數,無需自行加入或重複大括號。 這兩個 PHP 擴充甚至需要 ODBC 風格的轉義,即使是 SQLSRV 陣列選項和 PDO 建構參數:將每個右大括號寫成兩個,值則以大括號包覆。 每個程式在將這些值傳給驅動程式前,先執行一次此操作。 外大括號保留值開頭和結尾的字面大括號,並防止資料庫名稱內的分號分隔 PDO DSN 設定。 此逸出與 Transact-SQL(T-SQL)參數綁定是分開的。
用 SQLSRV 開啟、查詢並關閉
將此程式儲存為 connect-sqlsrv.php,並執行 php connect-sqlsrv.php。 它執行 T-SQL 查詢時,不建立資料表或更改資料。
CharacterSet 選擇 UTF-8 作為字元資料;它不會改變資料庫的欄位類型或排序方式。
<?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 {
$sql = "SELECT CAST(42 AS int) AS Value, N'caf' + NCHAR(233) AS Label, "
. "CAST(NULL AS int) AS Missing";
$stmt = sqlsrv_query($conn, $sql, [], ['QueryTimeout' => 30]);
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 !== ['Value' => 42, 'Label' => "caf\u{00e9}", 'Missing' => null]) {
throw new RuntimeException('Unexpected SQLSRV values or PHP types.');
}
echo json_encode($row, JSON_THROW_ON_ERROR), PHP_EOL;
} finally {
if (is_resource($stmt)) {
sqlsrv_free_stmt($stmt);
}
sqlsrv_close($conn);
}
預期產出:
{"Value":42,"Label":"caf\u00e9","Missing":null}
連線和陳述式是 PHP 資源,是你傳給 sqlsrv_* 函式的 handle。 使用任何一個把手前都要先檢查是否有 false。 失敗後立即擷取 sqlsrv_errors() ,因為後續的 SQLSRV 呼叫可能會取代錯誤集合。
SQLSRV_FETCH_ASSOC 回傳一個以欄名為鍵的關聯陣列。
SQLSRV_FETCH_NUMERIC 回傳以零為基礎的數字鍵;預設 SQLSRV_FETCH_BOTH 包含兩種形式。 對於 sqlsrv_fetch_array(), null 表示沒有更多的列數,且 false 表示錯誤。 列內的 SQL NULL 是 PHP null;這不代表該資料列不存在。
===用來區分這些數值。
開啟、查詢及關閉 PDO_SQLSRV
將這個獨立程式儲存為 connect-pdo.php,並在相同環境下執行 php connect-pdo.php 。
sqlsrv: 選擇PDO_SQLSRV,而非 PHP 的通用PDO_ODBC驅動程式。
<?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::ATTR_DEFAULT_FETCH_MODE => PDO::FETCH_ASSOC,
PDO::SQLSRV_ATTR_ENCODING => PDO::SQLSRV_ENCODING_UTF8,
]
);
$stmt = null;
try {
$sql = "SELECT CAST(42 AS int) AS Value, N'caf' + NCHAR(233) AS Label, "
. "CAST(NULL AS int) AS Missing";
$stmt = $pdo->prepare($sql, [PDO::SQLSRV_ATTR_QUERY_TIMEOUT => 30]);
$stmt->execute();
$row = $stmt->fetch();
if ($row !== ['Value' => '42', 'Label' => "caf\u{00e9}", 'Missing' => null]) {
throw new RuntimeException('Unexpected PDO_SQLSRV values or PHP types.');
}
echo json_encode($row, JSON_THROW_ON_ERROR), PHP_EOL;
} finally {
$stmt = null;
$pdo = null;
}
預期產出:
{"Value":"42","Label":"caf\u00e9","Missing":null}
PDO_SQLSRV 預設會將此 整數 欄位以 PHP 字串回傳。 若要請求支援的數值欄位的 PHP 數值型別,請設 PDO::SQLSRV_ATTR_FETCHES_NUMERIC_TYPE 為 true。 不要隨意使用 PHP 鑄造用於 十進位 值;浮點轉換可能會損失精確度。
PDO 屬性是連線或語句物件上的設定。 將 PDO::ATTR_ERRMODE 與 PDO::ERRMODE_EXCEPTION 一起使用會使資料庫操作失敗時拋出 PDOException。 連線建構在失敗時都會擲出錯誤,無論該設定為何。
PDO::FETCH_ASSOC 給出命名鍵, PDO::FETCH_NUM 給出以零為基礎的數值鍵, 並 PDO::FETCH_BOTH 同時給出兩者。
fetch() 結果結束時回傳 false ;同一列內的 SQL NULL 值仍為 PHP null。
這些命令列程式會在發生失敗時停止執行。 在網頁應用程式中,在處理請求的程式碼中捕捉例外。 在受保護的日誌中記錄診斷細節,並回傳通用錯誤回應。 不要向瀏覽器傳送 sqlsrv_errors()、例外狀況追蹤、連線字串或權杖。
選擇驗證模式
| Mode | 用途 | 看! |
|---|---|---|
| SQL Server 認證 | 當 Microsoft Entra ID 不可用時,使用本地 SQL Server、容器與 Azure SQL | 使用 SQL Server 認證連接 |
| 整合驗證(連線設定中沒有使用者名稱或密碼) | Windows 身分識別,或為 Kerberos 設定的 Linux/macOS 用戶端 | 使用 Windows 驗證連線 |
Microsoft Entra ID(Authentication 或 AccessToken 關鍵字) |
已設定為使用 Microsoft Entra ID 的 Azure SQL 和 Fabric SQL 目標 | 使用 Microsoft Entra 驗證進行連線 |
對於 SQL 驗證,SQLSRV 在其連線選項陣列中接受 UID 和 PWD。 PDO_SQLSRV 將使用者名稱和密碼作為傳遞給 new PDO() 的第二和第三個參數,而不是作為 DSN 關鍵字。 對於存取權杖,SQLSRV 會在選項陣列中接收 AccessToken,而 PDO_SQLSRV 則是在 DSN 中接收它。
如果你省略使用者名稱、密碼、Authentication 和 AccessToken,兩個驅動程式都會使用 Trusted_Connection=Yes 向 ODBC 請求整合認證。 在 Linux 和 macOS 上,此請求需要有效的 Kerberos 工單及 ODBC 整合驗證設定。 它不會讓任意的本地帳號存取遠端伺服器。
設定連線及其陳述式
連線設定會套用到你開啟的會話。 陳述式設定適用於特定查詢。 當應用程式需要非預設值時,請明確設定逾時和結果類型。
| Purpose | SQLSRV | PDO_SQLSRV | 行為擁有者 |
|---|---|---|---|
| 端點與資料庫 | 伺服器引數與 Database 選項。 |
Server 以及 Database DSN 關鍵字 |
ODBC 與 SQL 目標。 |
| SQL 憑證 |
UID 還有 PWD 選項。 |
建構函式的使用者名稱與密碼參數。 | 擴充功能憑證處理與伺服器認證。 |
| Microsoft Entra 認證 |
Authentication 選項,或是獨立 AccessToken 選項。 |
Authentication 或 AccessToken DSN 關鍵字,使用外部權杖時省略認證資訊。 |
ODBC 認證;應用程式會取得外部代幣。 |
| Encryption |
Encrypt => true。 |
Encrypt=true 在DSN中。 |
ODBC 傳輸安全。 |
| 憑證驗證 |
TrustServerCertificate => false。 |
TrustServerCertificate=false 在DSN中。 |
ODBC 以及作業系統的憑證信任設定。 |
| 連線建立逾時 |
LoginTimeout 連線選項,以秒為單位。 |
LoginTimeout DSN 關鍵字,以秒為單位。 |
ODBC。 這不是陳述式執行逾時。 |
| 查詢逾時 |
QueryTimeout statement 選項,以秒為單位。 |
PDO::SQLSRV_ATTR_QUERY_TIMEOUT,關於該連線或陳述式。 |
擴充功能與 ODBC 陳述式處理。 |
| 字元編碼 |
CharacterSet => 'UTF-8' 連線選項。 |
PDO::SQLSRV_ATTR_ENCODING => PDO::SQLSRV_ENCODING_UTF8。 |
PHP 擴充套件轉換。 PDO_SQLSRV預設為 UTF-8;SQLSRV 預設為系統編碼。 |
| 日期與時間物件 |
ReturnDatesAsStrings 預設是 false ,因此日期和時間欄位會回傳 DateTime 物件。 |
預設是字串;用 PDO::SQLSRV_ATTR_FETCHES_DATETIME_TYPE 來請求物件。 |
PHP 擴充功能型別轉換。 |
| 多重作用中結果集 (MARS) |
MultipleActiveResultSets 連線選項。 |
MultipleActiveResultSets DSN 關鍵字。 |
ODBC 和目標平台支援。 兩個擴充功能預設會啟用它;針對 Fabric 中的 Warehouse 停用它。 |
| 閒置恢復 |
ConnectRetryCount 以及 ConnectRetryInterval 連接選項。 |
同樣的 DSN 關鍵字。 | ODBC。 它們不會重試任意應用程式作業。 |
完整關鍵字清單、允許值與預設值,請參見 連線選項。 不要在 PDO DSN 中放置 CharacterSet、QueryTimeout 或 PDO:: 常數名稱。
管理連線存留期
當請求或工作需要資料庫工作時,請開啟連線。 在整個請求或工作過程中重複使用它,完成後再釋放它。 不要每列都連線與中斷連線。 在長時間運行的 worker 中,先釋放 statement 並完成每一筆交易,然後再接受下一個工作。
當你關閉 SQLSRV 的連線時,SQLSRV 會關閉相關的陳述式。 明確提前釋放 statement 會釋放資源,但連線不會中斷。 對於 PDO,指派 $pdo = null 只會移除該變數的參考。 某個 PDOStatement 或其他變數仍可保留連結。 也要釋放那些參照。
closeCursor() 釋放待處理結果,以便該陳述式可重複使用;它不是連線關閉方法。
這兩個 API 都是從自動提交模式開始:成功的語句會提交,除非你開始交易作業,否則不需要另外的應用程式提交。 對於必須一起成功或失敗的寫入群組,則使用 sqlsrv_begin_transaction() 或 $pdo->beginTransaction(),然後明確提交或回滾。 關閉有未完成交易的連線嘗試回滾,而非提交。 不要只依賴關機清理來執行你的事務策略。 完整範例請參見 執行交易。
釋放 PHP 連線句柄不一定會關閉其實體網路連線。 ODBC 的池化可以將其保留以便重複使用。 池化並不是永久保留 PHP 資源的理由,PDO_SQLSRV 也不支援 PDO::ATTR_PERSISTENT => true。 關於平台特定的池化配置,請參見 連線集區。
將指南套用到你的 SQL 目標上
handle、fetch 和清理模式會套用在支援的 SQL 目標上的這兩個擴充功能。 連線端點、認證、網路存取及 SQL 能力各異。
| 標的 | 改編 |
|---|---|
| SQL Server | 這些程式使用 SQL 登入帳號。 在設定 PHP 程序身份時,整合認證是另一種選擇。 |
| Azure SQL Database | 使用邏輯伺服器主機名稱和指定的資料庫。 建議在這些程式中使用 Microsoft Entra 認證,而不是 SQL 憑證。 |
| Azure SQL 受控執行個體 | 使用實例端點及其網路存取需求。 不要假設你的工作站能存取私有端點。 |
| Azure Synapse Analytics | 在調整建立或修改物件的查詢前,請使用 SQL 池端點並檢查其 T-SQL 支援。 |
| Microsoft Fabric 中的 SQL 資料庫 | 使用其資料庫連線資訊及 Microsoft Entra 認證。 不要取代 SQL 分析端點。 |
| Microsoft Fabric 中的倉庫 | 使用其倉庫端點與資料庫、Microsoft Entra 認證,以及 MultipleActiveResultSets=false。 |
關於服務特定的設定,請參見 Azure 和 Fabric 連線。
排除連線問題
從失敗的步驟開始。 成功的傳輸控制協定(TCP)檢查並不代表認證或憑證驗證成功。
| 徵兆 | 支票 |
|---|---|
Call to undefined function sqlsrv_connect() |
執行中的 PHP 程序沒有載入 sqlsrv。 請檢查它的 php.ini 記錄以及啟動警告。 |
PDO 報表 could not find driver |
確認 pdo_sqlsrv 已載入該行程,並確認可在 PDO::getAvailableDrivers() 中看到 sqlsrv。 |
| 找不到 ODBC 驅動程式 | 安裝 Microsoft ODBC 驅動程式並檢查其註冊與架構。 安裝 PHP 擴充功能並不會安裝 ODBC。 |
| 連線逾時或找不到伺服器 | 檢查伺服器名稱、埠口、名稱解析、路由、防火牆規則,以及 SQL Server 是否在 TCP 上監聽。 |
| 憑證鏈或主機名稱驗證失敗 | 安裝正確的信任鏈,並使用憑證的主機名稱。 不要把 TrustServerCertificate=true 它當作生產上的修正。 |
| 登入失敗或資料庫無法開啟 | 檢查認證模式、資料庫名稱、登入/使用者映射以及權限。 省略憑證時,會要求使用整合式驗證;它不會選擇 SQL 驗證。 |
| 在終端機中可成功執行,但網頁請求失敗 | 比較 PHP 執行時、載入擴充功能、程序身份、環境變數及網路存取。 不要公開提供包含設定細節的 phpinfo() 頁面。 |
| 後續操作在已關閉的控制代碼上失敗 | 在所有陳述式作業中保持連線。 關閉連線後再建立新連線;舊的 handle 不會自動重新開啟。 |