Nota
O acesso a esta página requer autorização. Pode tentar iniciar sessão ou alterar os diretórios.
O acesso a esta página requer autorização. Pode tentar alterar os diretórios.
Utilize declarações explícitas para enviar uma cadeia de entrada como varchar ou nvarchar com um comprimento SQL especificado. Em alternativa, opte pelo dimensionamento adaptativo para começar com um comprimento escolhido e aumentar a declaração quando enviar valores mais longos.
Estas opções requerem a versão 5.14.0 ou posterior e aplicam-se apenas a PDO_SQLSRV, o controlador PHP Data Objects (PDO). Para SQLSRV, continue a indicar tipos SQL no array de parâmetros descrito em Especificar tipos de dados do SQL Server. Nenhuma das abordagens altera a definição da coluna de destino.
Escolha um método de declaração
| Method | Configuration | Behavior |
|---|---|---|
| Metadados explícitos de declarações | Chame PDOStatement::setAttribute(PDO::SQLSRV_ATTR_PARAM_METADATA, $metadata) depois de prepare. |
Aplica-se a bindParam, bindValue, e execute($params). |
| Metadados explícitos de ligação | Passe um array de declaração como quinto argumento de bindParam. |
Substitui toda a entrada de metadados da instrução para essa vinculação, incluindo a sua codificação opcional. |
| Dimensionamento adaptativo | Definir PDO::SQLSRV_ATTR_DEFAULT_STR_LENGTH na conexão antes de criar the declaração. |
Aplica-se a cadeias de entrada elegíveis sem uma declaração explícita. |
Sem metadados explícitos ou dimensionamento adaptativo, o comportamento de dimensionamento dos parâmetros existente permanece inalterado. Não precisa destas opções para consultas parametrizadas comuns.
Declarar uma cadeia de entrada
Cada declaração é um array com chaves de constantes inteiras e valores inteiros.
| Key | Value |
|---|---|
PDO::SQLSRV_PARAM_DECLARED_STR_TYPE |
PDO::SQLSRV_PARAM_DECLARED_STR_TYPE_VARCHAR ou 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 em Formato de Transformação Unicode de 16 bits (UTF-16). Use PDO::SQLSRV_PARAM_DECLARED_STR_LENGTH_MAX para varchar(max) ou nvarchar(max). |
PDO::SQLSRV_ATTR_ENCODING (opcional) |
A codificação de caracteres da cadeia de entrada PHP. Para entrada em formato de transformação Unicode de 8 bits (UTF-8), utilize PDO::SQLSRV_ENCODING_UTF8 ou PDO::SQLSRV_ENCODING_UTF8_VARCHAR. O tipo declarado, e não a codificação, define o tipo SQL. Também pode usar PDO::SQLSRV_ENCODING_SYSTEM como entrada na codificação do sistema. A codificação binária não é suportada. |
Deve incluir ambas as chaves de declaração. Cadeias numéricas, valores booleanos, comprimentos zero e chaves não reconhecidas são inválidas. Um carácter Unicode suplementar, como "\u{1F600}", ocupa duas unidades de código UTF-16, embora o PHP armazene a sua representação UTF-8 em quatro bytes.
A codificação descreve os bytes de origem. O tipo declarado descreve o parâmetro SQL enviado ao servidor. Por exemplo, pode enviar entrada UTF-8 como varchar sem alterar os bytes de origem para a codificação do sistema. A conversão para varchar ainda depende da ordenação SQL e do seu repertório de caracteres. Um comprimento SQL explícito não aloca um buffer PHP.
Quando o driver declara um parâmetro vinculado para uma instrução preparada, ignora os sinalizadores PDO::PARAM_STR_NATL e PDO::PARAM_STR_CHAR. Use uma declaração para escolher varchar ou nvarchar.
Para metadados de instrução, utilize um mapa dos identificadores de parâmetros para os arrays de declaração:
- Utilize posições baseadas em 1 para marcadores de interrogação, como
[1 => $declaration]. As posições devem ser inteiras de 1 a 2.100 e devem identificar parâmetros ligados quando executar. - Utilize um nome de marcador de posição único, com ou sem dois pontos, como
['name' => $declaration]ou[':name' => $declaration]. Um nome do marcador de posição repetido não identifica uma posição única. Não especifique a mesma posição duas vezes através de nomes diferentes ou chaves numéricas. - Defina metadados após
prepare, não no seu array de opções. Cada método setter bem-sucedido substitui todo o map e reinicia o histórico de tamanho adaptativo. Uma substituição inválida preserva o mapa anterior. Passe[]para limpar o mapa;nullé inválido. - Acione
getAttribute(PDO::SQLSRV_ATTR_PARAM_METADATA)na instrução para recuperar o mapa normalizado para posições baseadas em 1. Retorna metadados da instrução, não substituições por ligação nem histórico de tamanho adaptativo.
Um array passado para execute fornece valores, não declarações. Os seus valores posicionais usam o habitual array PHP baseado em zero, como ['text']; o seu mapa de metadados ainda utiliza [1 => $declaration].
Para bindParam, mantenha o quarto argumento em 0 para uma declaração de entrada. Um quarto argumento positivo seleciona o comportamento de buffer de saída; não é o novo comprimento de declaração SQL. As opções de codificação de inteiros no quinto argumento continuam a funcionar. Uma array de declarações sobrescreve toda a entrada da instrução para essa associação, enquanto uma opção de codificação de inteiros sobrepõe apenas a codificação. Rebinding sem o array de declaração remove a sobrescrita dessa ligação, mas mantém os metadados da instrução.
Exemplo: declarações explícitas
Os exemplos neste artigo assumem uma ligação aberta PDO em $conn que utiliza PDO::ERRMODE_EXCEPTION. Para abrir uma ligação, consulte Ligar ao servidor. Utilizam a tabela seguinte:
CREATE TABLE dbo.Customers
(
CustomerID int IDENTITY PRIMARY KEY,
Name nvarchar(100) NOT NULL,
Code varchar(10) NOT NULL
);
Sem declaração, o driver envia cada valor de cadeia nos exemplos seguintes como nvarchar(4000). Cada exemplo declara o tipo e o comprimento da coluna correspondente em vez disso.
O exemplo seguinte utiliza parâmetros nomeados, metadados da instrução e um array passado a execute. O servidor recebe @P1 nvarchar(100) e @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']);
O exemplo seguinte utiliza um marcador de ponto de interrogação e bindValue para encontrar um cliente por código. A chave 1 de metadados identifica o primeiro marcador de posição. A declaração de varchar(10) corresponde à coluna Code. Quando uma coluna varchar é comparada a um parâmetro nvarchar, o SQL Server converte o valor da coluna, o que pode impedir uma busca 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";
O exemplo seguinte passa um array de declaração como quinto argumento de bindParam, com 0 como quarto argumento. O comprimento declarado mantém-se fixo ao longo das execuções. Um valor com mais de 10 caracteres falha com SQLSTATE 22001 e não insere nenhuma linha.
$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";
}
Opte pelo dimensionamento adaptativo
Defina PDO::SQLSRV_ATTR_DEFAULT_STR_LENGTH no array de opções do construtor de ligação ou com PDO::setAttribute. O valor deve ser um número inteiro de 0 a 8.000. O padrão, 0, desativa o dimensionamento adaptativo.
Cada nova instrução copia a definição da ligação. Alterá-la mais tarde afeta novas instruções SQL, não as existentes. Este atributo não é uma instrução nem uma opção prepare.
Para cada posição de parâmetro elegível, o driver começa com o piso configurado e aumenta a declaração para se ajustar a valores mais longos. Mantém o maior tamanho utilizado nessa posição quando mais tarde envia valores mais curtos, vazios ou nulos. Para entrada UTF-8 com codificação padrão, utiliza nvarchar e mede o crescimento em unidades de código UTF-16. Para entrada codificada pelo sistema, utiliza varchar e reserva três bytes extra para cada byte não-ASCII, porque a conversão para uma ordenação UTF-8 pode alongar o valor. Promove declarações para além de 4.000 unidades nvarchar ou 8.000 bytes varchar para max, incluindo quando o piso inicial excede o limite limitado do tipo.
Declarações explícitas têm precedência sobre o dimensionamento adaptativo. Parâmetros ligados como inteiros, dados binários, fluxos ou parâmetros de saída ou de entrada/saída mantêm o seu comportamento existente. Alterar o tipo SQL inferido alterando a codificação inicia um novo histórico de tamanho para esse parâmetro.
Exemplo: dimensionamento adaptativo
O exemplo seguinte utiliza a tabela do exemplo de declaração explícita. Define um mínimo de 20 na ligação antes de preparar a instrução. A primeira execução envia @P1 nvarchar(20) e @P2 nvarchar(20). O segundo nome tem 30 caracteres, pelo que o driver cresce @P1 para nvarchar(30). Ambos os parâmetros são nvarchar porque a entrada é UTF-8, embora a coluna Code seja varchar. Para corresponder a uma coluna varchar , utilize uma declaração 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']);
A definição de tamanho controla as declarações dos parâmetros, não a capacidade da coluna de destino.
Limitações e erros
- Declarações explícitas suportam apenas cadeias de entrada e valores nulos ligados a
PDO::PARAM_STRouPDO::PARAM_NULL. Rejeitam codificação binária, streams, outros tipos de parâmetros e parâmetros de saída/entrada-saída. - Na versão 5.14.0, o varchar explícito limitado aceita apenas entrada ASCII (American Standard Code for Information Interchange). Para entrada não-ASCII, use nvarchar, varchar(max) com uma ordenação adequada ou dimensionamento adaptativo. O dimensionamento adaptativo não remove as restrições de conversão por agrupamento.
- Declarações explícitas e dimensionamento adaptativo não são suportados com Always Encrypted nem com preparações emuladas. Uma configuração adaptativa diferente de zero faz com que a criação de instruções falhe em qualquer um dos dois caminhos. Desative-o antes de criar essas declarações. A execução direta através de
PDO::SQLSRV_ATTR_DIRECT_QUERYé distinta das preparações emuladas e suporta estas declarações. - Metadados inválidos, caminhos de declaração não suportados e definições adaptativas inválidas reportam SQLSTATE
IMSSP. Uma entrada que exceda uma declaração limitada válida reporta22001. Trate os erros de acordo comPDO::ATTR_ERRMODE; os exemplos assumem o modo de exceção. - O controlador não procura a coluna de destino nem reescreve o teu Transact-SQL para escolher uma declaração. Escolha tipos e comprimentos que correspondam ao seu esquema.