使用显式声明以 varchar 或 nvarchar 形式发送输入字符串,并具有指定的 SQL 长度。 或者,选择启用自适应长度调整,从选定长度开始,在发送更长的值时再扩大声明。
这些选项需要版本 5.14.0 或更高版本,并且仅适用于 PDO_SQLSRV,PHP 数据对象(PDO)驱动程序。 对于 SQLSRV,请继续在“指定 SQL Server 数据类型”中描述的参数数组中指定 SQL 类型。 这两种方法都不会改变目标列的定义。
选择声明方法
| 方法 | Configuration | Behavior |
|---|---|---|
| 显式语句元数据 | 请在 prepare 后调用 PDOStatement::setAttribute(PDO::SQLSRV_ATTR_PARAM_METADATA, $metadata)。 |
适用于 bindParam、bindValue和execute($params)。 |
| 显式绑定元数据 | 将声明数组作为 bindParam 的第五个参数传入。 |
替换该绑定的整个语句元数据条目,包括其可选编码。 |
| 自适应大小 | 在创建语句之前先在连接上设置 PDO::SQLSRV_ATTR_DEFAULT_STR_LENGTH 。 |
适用于未明确声明的合格输入字符串。 |
如果没有显式元数据或自适应定型,现有的参数定型行为保持不变。 对于普通参数化查询,您不需要这些选项。
声明输入字符串
每个声明都是一个数组,包含整数常量键和整数值。
| Key | 价值 |
|---|---|
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位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 和 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中有一个使用PDO::ERRMODE_EXCEPTION的开放$conn连接。 要打开连接,请参见 “连接到服务器”。 他们使用以下表格:
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 选项。
对于每个符合条件的参数位置,驱动程序从配置的下限开始,并扩展声明以适应更长的值。 当你以后发送更短、空字符串或 null 值时,它会保留该位置使用的最大大小。 对于默认编码的 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) 搭配合适的排序规则或自适应大小。 自适应调整尺寸并不能消除排序转换的限制。
- “始终加密”或 模拟预处理不支持显式声明和自适应尺寸调整。 非零自适应设置会导致任一路径的语句创建失败。 在创建这些声明之前先将其禁用。 通过
PDO::SQLSRV_ATTR_DIRECT_QUERY直接执行不同于模拟预处理,并支持这些声明。 - 无效的元数据、不受支持的声明路径以及无效的自适应设置将报告 SQLSTATE
IMSSP。 超过有效有界声明的输入会报告22001。 根据PDO::ATTR_ERRMODE处理错误;示例假设异常模式。 - 驱动程序不会查找目标列,也不会重写你的 Transact-SQL 来选择声明方式。 选择与您的架构相匹配的类型和长度。