Nota:
El acceso a esta página requiere autorización. Puede intentar iniciar sesión o cambiar directorios.
El acceso a esta página requiere autorización. Puede intentar cambiar los directorios.
Utilice declaraciones explícitas para enviar una cadena de entrada como varchar o nvarchar con una longitud SQL especificada. Alternativamente, opta por el dimensionamiento adaptativo para comenzar con una longitud elegida y ampliar la declaración cuando envíes valores más largos.
Estas opciones requieren la versión 5.14.0 o posterior y se aplican solo a PDO_SQLSRV, el controlador PHP Data Objects (PDO). Para SQLSRV, continúe especificando tipos SQL en el array de parámetros descrito en Especificar tipos de datos de SQL Server. Ninguno de los dos enfoques cambia la definición de la columna de destino.
Elige un método de declaración
| Method | Configuration | Behavior |
|---|---|---|
| Metadatos de declaración explícita | Llamada a PDOStatement::setAttribute(PDO::SQLSRV_ATTR_PARAM_METADATA, $metadata) después de prepare. |
Se aplica a bindParam, bindValue, y execute($params). |
| Metadatos explícitos de enlace | Pasar un array de declaración como quinto argumento de bindParam. |
Reemplaza toda la entrada de metadatos de la instrucción para esa vinculación, incluida su codificación opcional. |
| Dimensionamiento adaptativo | Configura PDO::SQLSRV_ATTR_DEFAULT_STR_LENGTH en la conexión antes de crear la instrucción. |
Se aplica a cadenas de entrada elegibles sin una declaración explícita. |
Sin metadatos explícitos ni dimensionamiento adaptativo, el comportamiento de dimensionamiento de parámetros existente permanece sin cambios. No necesitas estas opciones para consultas parametrizadas ordinarias.
Declarar una cadena de entrada
Cada declaración es un array con claves constantes enteras y valores enteros.
| Key | Value |
|---|---|
PDO::SQLSRV_PARAM_DECLARED_STR_TYPE |
PDO::SQLSRV_PARAM_DECLARED_STR_TYPE_VARCHAR o PDO::SQLSRV_PARAM_DECLARED_STR_TYPE_NVARCHAR. |
PDO::SQLSRV_PARAM_DECLARED_STR_LENGTH |
Para varchar, de 1 a 8.000 bytes. Para nvarchar, de 1 a 4.000 unidades de código en formato de transformación Unicode de 16 bits (UTF-16). Use PDO::SQLSRV_PARAM_DECLARED_STR_LENGTH_MAX para varchar(max) o nvarchar(max). |
PDO::SQLSRV_ATTR_ENCODING (opcional) |
La codificación de caracteres de la cadena de entrada PHP. Para la entrada en formato de transformación Unicode de 8 bits (UTF-8), use PDO::SQLSRV_ENCODING_UTF8 o PDO::SQLSRV_ENCODING_UTF8_VARCHAR. El tipo declarado, no la codificación, establece el tipo SQL. También puedes usar PDO::SQLSRV_ENCODING_SYSTEM como entrada en la codificación del sistema. No se admite codificación binaria. |
Debes incluir ambas claves de declaración. Las cadenas numéricas, valores booleanos, longitudes cero y claves no reconocidas son inválidas. Un carácter Unicode suplementario, como "\u{1F600}", ocupa dos unidades de código UTF-16, aunque PHP almacena su representación UTF-8 en cuatro bytes.
La codificación describe los bytes fuente. El tipo declarado describe el parámetro SQL enviado al servidor. Por ejemplo, puedes enviar una entrada UTF-8 como varchar sin cambiar los bytes de origen a la codificación del sistema. La conversión a varchar sigue dependiendo de la ordenación SQL y de su repertorio de caracteres. Una longitud SQL explícita no asigna un búfer PHP.
Cuando el controlador declara un parámetro vinculado para una instrucción preparada, ignora las marcas PDO::PARAM_STR_NATL y PDO::PARAM_STR_CHAR. Usa una declaración para elegir varchar o nvarchar.
Para metadatos de sentencias, utilice un mapa desde identificadores de parámetros hasta matrices de declaración:
- Utiliza posiciones basadas en 1 para marcadores de posición con signo de interrogación, como
[1 => $declaration]. Las posiciones deben ser enteros del 1 al 2.100 y deben identificar los parámetros vinculados al ejecutar. - Utilice un nombre de marcador de posición único, con o sin los dos puntos, como
['name' => $declaration]o[':name' => $declaration]. Un nombre de marcador de posición repetido no identifica una posición única. No especifiques la misma posición dos veces con nombres diferentes o claves numéricas. - Establecer metadatos después de
prepare, no en su matriz de opciones. Cada setter exitoso reemplaza todo el map y reinicia el historial de tamaño adaptativo. Un reemplazo inválido conserva el mapa anterior. Pasar[]para borrar el mapa;nulles inválido. - Llama
getAttribute(PDO::SQLSRV_ATTR_PARAM_METADATA)a la sentencia para recuperar el mapa normalizado a posiciones basadas en 1. Devuelve metadatos de la sentencia, no anulaciones por vinculación ni historial de tamaño adaptativo.
Un array pasado a execute suministra valores, no declaraciones. Sus valores posicionales utilizan el habitual array PHP basado en ceros, como ['text']; su mapa de metadatos sigue utilizando [1 => $declaration].
Para bindParam, mantenga el cuarto argumento en 0 para una declaración de entrada. Un cuarto argumento positivo selecciona el comportamiento del buffer de salida; no es la nueva longitud de la declaración SQL. Las opciones de codificación entera en el quinto argumento siguen funcionando. Un array de declaración sobrescribe toda la entrada de la instrucción para esa vinculación, mientras que una opción de codificación entera sobrescribe únicamente la codificación. Reasignar sin el array de declaración elimina la sobrescritura de esa vinculación, pero conserva los metadatos de la sentencia.
Ejemplo: declaraciones explícitas
Los ejemplos de este artículo suponen una conexión abierta PDO en $conn que utiliza PDO::ERRMODE_EXCEPTION. Para abrir uno, consulte Conexión al servidor. Utilizan la siguiente tabla:
CREATE TABLE dbo.Customers
(
CustomerID int IDENTITY PRIMARY KEY,
Name nvarchar(100) NOT NULL,
Code varchar(10) NOT NULL
);
Sin declaración, el controlador envía cada valor de cadena en los siguientes ejemplos como nvarchar(4000). Cada ejemplo declara en su lugar el tipo y la longitud de la columna correspondiente.
El siguiente ejemplo utiliza parámetros con nombre, metadatos de sentencias y un array pasado a execute. El servidor recibe @P1 nvarchar(100) y @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']);
El siguiente ejemplo utiliza un marcador de posición con signo de interrogación y bindValue para encontrar un cliente por código. La clave 1 de metadatos identifica el primer marcador de posición. La declaración de varchar(10) coincide con la columna Code. Cuando se compara una columna varchar con un parámetro nvarchar, SQL Server convierte el valor de la columna, lo que puede impedir una búsqueda de índice.
$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";
El siguiente ejemplo pasa un array de declaración como quinto argumento de bindParam, con 0 como cuarto argumento. La longitud declarada permanece fija a lo largo de las ejecuciones. Un valor de más de 10 caracteres falla con SQLSTATE 22001 y no inserta ninguna fila.
$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";
}
Opta por el dimensionamiento adaptativo
Establece PDO::SQLSRV_ATTR_DEFAULT_STR_LENGTH en el array de opciones del constructor de conexión o con PDO::setAttribute. El valor debe ser un número entero de 0 a 8.000. La opción predeterminada, 0, desactiva el dimensionamiento adaptativo.
Cada nueva instrucción copia la configuración de conexión. Cambiarlo más tarde afecta a las nuevas sentencias, no a las existentes. Este atributo no es una declaración ni una opción de prepare.
Para cada posición de parámetro elegible, el controlador comienza con el límite mínimo configurado y expande la declaración para ajustarse a valores más largos. Conserva el tamaño más grande utilizado en esa posición cuando más tarde envías valores más cortos, vacíos o nulos. Para la entrada UTF-8 con la codificación predeterminada, utiliza nvarchar y mide el crecimiento en unidades de código UTF-16. Para la entrada codificada por sistema, utiliza varchar y reserva tres bytes adicionales para cada byte no ASCII, porque la conversión a una ordenación UTF-8 puede alargar el valor. Promueve declaraciones superiores a 4.000 unidades nvarchar o 8.000 bytes varchar hasta max, incluso cuando el piso inicial supera el límite acotado del tipo.
Las declaraciones explícitas tienen prioridad sobre el dimensionamiento adaptativo. Los parámetros vinculados como enteros, datos binarios, flujos o parámetros de salida o de entrada/salida mantienen su comportamiento existente. Cambiar el tipo SQL inferido cambiando la codificación inicia un nuevo historial de tamaño para ese parámetro.
Ejemplo: dimensionamiento adaptativo
El siguiente ejemplo utiliza la tabla del ejemplo de declaración explícita. Establece un nivel mínimo de 20 en la conexión antes de preparar la sentencia. La primera ejecución envía @P1 nvarchar(20) y @P2 nvarchar(20). El segundo nombre tiene 30 caracteres, por lo que el controlador amplía @P1 a nvarchar(30). Ambos parámetros son nvarchar porque la entrada es UTF-8, aunque la columna Code sea varchar. Para coincidir con una columna varchar , utilice una declaración explícita.
$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']);
La configuración de tamaño controla las declaraciones de parámetros, no la capacidad de la columna de destino.
Limitaciones y errores
- Las declaraciones explícitas solo admiten cadenas de entrada y valores nulos vinculados con
PDO::PARAM_STRoPDO::PARAM_NULL. Rechazan la codificación binaria, los flujos, otros tipos de parámetros y los parámetros de salida/entrada-salida. - En la versión 5.14.0, el varchar explícito acotado acepta únicamente entrada del Código Estándar Americano para el Intercambio de Información (ASCII). Para entradas no ASCII, use nvarchar, varchar(max) con una ordenación adecuada o dimensionamiento adaptativo. El dimensionamiento adaptativo no elimina las restricciones de conversión por intercalación.
- No se admiten declaraciones explícitas ni dimensionamiento adaptativo con Always Encrypted ni con las preparaciones emuladas. Una configuración adaptativa distinta de cero hace que la creación de sentencias falle para cualquiera de las rutas. Desactívalo antes de crear esas sentencias. La ejecución directa a través de
PDO::SQLSRV_ATTR_DIRECT_QUERYes distinta de las preparaciones emuladas y soporta estas declaraciones. - Metadatos no válidos, rutas de declaración no compatibles y configuraciones adaptativas no válidas informan SQLSTATE
IMSSP. Una entrada que exceda una declaración acotada válida reporta22001. Gestiona errores segúnPDO::ATTR_ERRMODE; los ejemplos asumen el modo de excepción. - El controlador no busca la columna de destino ni reescribe tu Transact-SQL para elegir una declaración. Elige tipos y longitudes que coincidan con tu esquema.