Объявить типы и длину входных строк (PDO_SQLSRV)

Используйте явные объявления для отправки входной строки как varchar или nvarchar с заданной длиной SQL. В качестве альтернативы выберите адаптивный размер, чтобы начать с выбранной длины и увеличивать размер объявления при отправке более длинных значений.

Для этих опций требуется версия 5.14.0 или новее, и они применяются только к PDO_SQLSRV, драйверу PHP Data Objects (PDO). Для SQLSRV продолжайте указывать типы SQL в массиве параметров, описанном в разделе «Указать типы данных SQL Server». Ни один из подходов не изменяет определение столбца назначения.

Выберите метод объявления

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 — от 1 до 4000 кодовых единиц в 16-битном формате преобразования Unicode (UTF-16). Используйте PDO::SQLSRV_PARAM_DECLARED_STR_LENGTH_MAX для varchar(max) или nvarchar(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 в $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";
}

Включите адаптивный размер

Установите 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']);

Настройка размера управляет объявлениями параметров, а не емкостью столбца назначения.

Ограничения и ошибки

  • Явные объявления поддерживают только входные строки и значения null, связанные с PDO::PARAM_STR или PDO::PARAM_NULL. Они отвергают двоичное кодирование, потоки, другие типы параметров и выходные параметры и параметры ввода-вывода.
  • В версии 5.14.0 ограниченный явный varchar принимает только ввод в кодировке American Standard Code for Information Interchange (ASCII). Для ввода, содержащего не-ASCII-символы, используйте nvarchar, varchar(max) с подходящей сортировкой или адаптивный размер. Адаптивное изменение размеров не устраняет ограничения преобразования правил сортировки.
  • Явные объявления и адаптивное изменение размеров не поддерживаются в Always Encrypted или эмулируемых prepare-выражениях. Ненулевой адаптивный параметр приводит к сбою при создании инструкций для любого из путей. Отключите его перед созданием этих инструкций. Прямое исполнение через PDO::SQLSRV_ATTR_DIRECT_QUERY отличается от эмулируемой подготовки запросов и поддерживает эти объявления.
  • Недопустимые метаданные, неподдерживаемые пути объявления и недопустимые адаптивные настройки возвращают SQLSTATE IMSSP. При вводе, превышающем допустимые границы объявления, возвращается 22001. Обрабатывайте ошибки согласно PDO::ATTR_ERRMODE; в примерах предполагается режим исключений.
  • Драйвер не ищет столбец назначения и не переписывает ваш Transact-SQL, чтобы выбрать объявление. Выбирайте типы и длины, соответствующие вашей схеме.