声明输入字符串类型和长度(PDO_SQLSRV)

使用显式声明以 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 来选择声明方式。 选择与您的架构相匹配的类型和长度。