宣告輸入字串類型與長度(PDO_SQLSRV)

使用明確宣告將輸入字串以 varchar 或 nvarchar 形式傳送,並指定 SQL 長度。 或者,您也可以選擇啟用自適應尺寸,從選定的長度開始,並在傳送較長的值時擴大宣告。

這些選項需要版本 5.14.0 或更新版本,且僅適用於 PDO_SQLSRV,也就是 PHP 資料物件(PDO)驅動程式。 對於 SQLSRV,請繼續在「指定 SQL Server 資料型別」中描述的參數陣列中指定 SQL 類型。 兩種方法都不會改變目的地欄位的定義。

選擇宣告方法

Method 設定 Behavior
明確陳述中繼資料 在PDOStatement::setAttribute(PDO::SQLSRV_ATTR_PARAM_METADATA, $metadata)之後撥打prepare。 適用於 bindParam、 bindValue和 execute($params)。
明確綁定中繼資料 將宣告陣列作為 bindParam 的第五個參數傳遞。 取代該綁定的整個語句中繼資料條目,包括其可選編碼。
自動調整大小 在建立語句前先在連線上設定 PDO::SQLSRV_ATTR_DEFAULT_STR_LENGTH。 適用於未明確宣告的符合條件輸入字串。

若沒有明確的元資料或自適應尺寸設定,現有的參數大小行為將保持不變。 一般參數化查詢不需要這些選項。

宣告輸入字串

每個宣告都是一個陣列,包含整數常數鍵與整數值。

Key Value
PDO::SQLSRV_PARAM_DECLARED_STR_TYPE PDO::SQLSRV_PARAM_DECLARED_STR_TYPE_VARCHAR 或 PDO::SQLSRV_PARAM_DECLARED_STR_TYPE_NVARCHAR。
PDO::SQLSRV_PARAM_DECLARED_STR_LENGTH 對於 varchar,1 到 8,000 位元組。 對於 nvarchar,則為 16 位元 Unicode 轉換格式(UTF-16)的 1 至 4,000 碼單位。 對 varchar(max) 或 nvarchar(max) 使用 PDO::SQLSRV_PARAM_DECLARED_STR_LENGTH_MAX。
PDO::SQLSRV_ATTR_ENCODING (可選) PHP 輸入字串的字元編碼。 若要輸入 8-bit Unicode 轉換格式(UTF-8),請使用 PDO::SQLSRV_ENCODING_UTF8 或 PDO::SQLSRV_ENCODING_UTF8_VARCHAR。 設定 SQL 類型由宣告的型別,而非編碼本身。 您也可以將 PDO::SQLSRV_ENCODING_SYSTEM 用於系統編碼的輸入。 不支援二進位編碼。

您必須包含兩個宣告金鑰。 數值字串、布林值、零長度及未識別的鍵碼皆無效。 一個輔助的 Unicode 字元,例如 "\u{1F600}",會佔用兩個 UTF-16 編碼單元,儘管 PHP 將其 UTF-8 表示方式儲存為四個位元組。

編碼描述來源位元組。 宣告的類型描述傳送給伺服器的 SQL 參數。 例如,你可以將 UTF-8 輸入以 varchar 形式傳送,而不必將來源位元組變更為系統編碼。 轉換成 varchar 仍依賴 SQL 排序規則 及其字元集。 明確的 SQL 長度不會分配 PHP 緩衝區。

當驅動程式宣告已準備語句的綁定參數時,會忽略 PDO::PARAM_STR_NATL and PDO::PARAM_STR_CHAR 標記。 使用宣告來選擇 varchar 或 nvarchar。

對於語句中繼資料,請使用從參數識別碼到宣告陣列的映射:

  • 請使用以 1 為基礎的位置作為問號佔位符,例如 [1 => $declaration]。 位置必須是 1 到 2,100 的整數,且在執行時必須用來識別繫結參數。
  • 使用獨特的佔位符名稱,可有或無冒號,例如 ['name' => $declaration] 或 [':name' => $declaration]。 重複的佔位名稱並不會識別一個獨特的位置。 不要用不同名稱或數字鍵重複指定相同位置。
  • 將元資料設定在 prepare 之後,而不是在其選項陣列中。 每成功設定一次,就會取代整個映射,並重設自適應尺寸歷史。 無效的替換會保留先前的映射。 傳入 [] 以清除對應表;null 無效。
  • 在該陳述式上呼叫 getAttribute(PDO::SQLSRV_ATTR_PARAM_METADATA) 以取得標準化為以 1 為基礎位置的映射。 它會回傳陳述式中繼資料,而非每個綁定的覆寫或自適應大小歷史。

傳遞給 execute 供應的陣列是值,而非宣告。 其位置值使用通常以零為基礎的 PHP 陣列,例如 ['text'];其元資料映射仍使用 [1 => $declaration]。

對於 bindParam,將第四個參數保持為 0,作為輸入宣告。 正向的第四個參數選擇輸出緩衝區的行為;它並不是新的 SQL 宣告長度。 第五個參數中的整數編碼選項仍然有效。 宣告陣列會覆蓋該綁定的整個語句條目,而整數編碼選項則僅覆蓋編碼本身。 在沒有宣告陣列的情況下重新綁定會移除該綁定的覆寫,但保留語句的中繼資料。

範例:明確宣告

本文範例假設在 PDO 中有一個$conn開啟的連線,且使用 PDO::ERRMODE_EXCEPTION。 若要開啟連線,請參閱 「連線至伺服器」。 他們使用以下表格:

CREATE TABLE dbo.Customers
(
    CustomerID int IDENTITY PRIMARY KEY,
    Name nvarchar(100) NOT NULL,
    Code varchar(10) NOT NULL
);

若不宣告,驅動程式會將以下範例中的每個字串值傳送為 nvarchar(4000)。 每個範例則宣告匹配欄位的類型與長度。

以下範例使用命名參數、語句元資料,以及傳入給 execute的陣列。 伺服器接收 @P1 nvarchar(100) 和 @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']);

以下範例使用問號佔位符和 bindValue 依代碼尋找客戶。 元資料金鑰 1 用來識別第一個佔位符。 宣告 varchar(10) 會與 Code 欄位相符。 當 varchar 欄位與 nvarchar 參數比較時,SQL Server 會轉換欄位值,這可能會阻止索引搜尋。

$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";

以下範例將宣告陣列作為 bindParam 的第五個參數傳入,並將 0 作為第四個參數。 宣告的長度在執行間保持固定。 超過 10 個字元的值會失敗,並傳回 SQLSTATE 22001,且不會插入任何列。

$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";
}

選擇啟用自適應大小調整

在連線建構子的 options 陣列中設定 PDO::SQLSRV_ATTR_DEFAULT_STR_LENGTH,或使用 PDO::setAttribute。 該值必須為 0 到 8,000 的整數。 預設 0 值,會停用自動調整大小。

每一個新的語句都會複製連線設定。 之後更改它影響的是新的陳述式,而不是現有的陳述式。 此屬性不是陳述或 prepare 選項。

對於每個符合條件的參數位置,驅動程式從設定的下限開始,並擴大宣告以適合更長的值。 當您之後傳送較短、空字串或空值時,它會保留該位置所用的最大大小。 對於預設編碼的 UTF-8 輸入,它使用 nvarchar ,並以 UTF-16 編碼單位衡量成長。 對於系統編碼的輸入,它使用 varchar ,並為每個非 ASCII 位元組保留三個額外位元組,因為轉換成 UTF-8 排序規則可能會使該值變長。 它會將超過 4,000 個 nvarchar 單位或 8,000 個 varchar 位元組的宣告提升為 max,包括初始下限超過該型別有界限制的情況。

明確宣告優先於自動調整大小。 綁定為整數、二進位資料、串流或輸出/輸入輸出參數的參數會保留其既有行為。 透過變更編碼來變更推斷出的 SQL 類型,會啟動該參數的新大小歷史。

範例:自適應調整大小

以下範例使用了明確宣告範例中的資料表。 它會在準備陳述式前,先設定連線的底線為 20。 第一次執行會 @P1 nvarchar(20) 傳送 和 @P2 nvarchar(20)。 第二個名稱有 30 個字元,因此驅動程式會將 @P1 擴展為 nvarchar(30)。 兩個參數都是 nvarchar ,因為輸入是 UTF-8,儘管 Code 欄位是 varchar。 若要匹配 varchar 欄位,請使用明確宣告。

$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']);

大小設定控制的是參數宣告,而非目的欄位的容量。

限制與錯誤

  • 明確宣告僅支援以 PDO::PARAM_STR 或 PDO::PARAM_NULL綁定的輸入字串與空值。 它們拒絕二進位編碼、串流、其他參數類型,以及輸出參數和輸入/輸出參數。
  • 在 5.14.0 版本中,有界明確 varchar 只接受美國標準資訊交換碼(ASCII)輸入。 對於非 ASCII 輸入,請使用 nvarchar、varchar(max) 搭配適當的排序規則,或自動調整大小。 自適應大小調整並不會消除排序規則轉換的限制。
  • Always Encrypted 或 模擬 prepare 不支援明確宣告與自適應大小設定。 非零的自適應設定會使任一條路徑的陳述式建立失敗。 在建立這些陳述式之前先停用它。 直接執行 PDO::SQLSRV_ATTR_DIRECT_QUERY 與模擬準備不同,並支援這些宣告。
  • 無效的元資料、不支援的宣告路徑,以及無效的自適應設定會回報 SQLSTATE IMSSP。 超過有效有界宣告的輸入會回報 22001。 依照 PDO::ATTR_ERRMODE 處理錯誤;以下範例假設例外模式。
  • 驅動程式不會查詢目標欄位,也不會重寫你的 Transact-SQL 來選擇宣告方式。 選擇與結構描述相符的類型與長度。