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.
Prepara uma declaração para execução.
Sintaxe
PDOStatement PDO::prepare ( $statement [ , array(key_pair) ] )
Parameters
$ Enunciado
Uma cadeia de caracteres contendo a instrução SQL.
key_pair
Um array contendo um nome e valor de atributo. Para obter mais informações, consulte a seção
Valor de retorno
Devolve um PDOStatement objeto em caso de sucesso. Em caso de falha, devolve um PDOException objeto, ou false dependendo do valor de PDO::ATTR_ERRMODE.
Remarks
Os drivers Microsoft para PHP para SQL Server não avaliam instruções preparadas até à execução.
Para declarar tipos e comprimentos SQL de string de entrada, defina PDO::SQLSRV_ATTR_PARAM_METADATA na instrução retornada, não no prepare array de opções. Para dimensionamento adaptativo, defina PDO::SQLSRV_ATTR_DEFAULT_STR_LENGTH a ligação antes de chamar prepare; a nova instrução copia essa definição. Para exemplos e limitações, consulte Declarar tipos e comprimentos de string de entrada (PDO_SQLSRV).
A tabela seguinte lista os possíveis valores de key_pair .
| Key | Description |
|---|---|
PDO::ATTR_CURSOR |
Especifica o comportamento do cursor. O predefinido é PDO::CURSOR_FWDONLY, um cursor frontal não deslocável.
PDO::CURSOR_SCROLL é um cursor deslocável.Por exemplo, array( PDO::ATTR_CURSOR => PDO::CURSOR_FWDONLY ).Quando definido como PDO::CURSOR_SCROLL, pode então usar PDO::SQLSRV_ATTR_CURSOR_SCROLL_TYPE para definir o tipo de cursor deslocável, que é descrito mais adiante neste artigo.Consulte Tipos de Cursor (PDO_SQLSRV Driver) para mais informações sobre conjuntos de resultados e cursores no PDO_SQLSRV driver. |
PDO::ATTR_EMULATE_PREPARES |
Por predefinição, este atributo é falso, o que pode ser alterado por este PDO::ATTR_EMULATE_PREPARES => true.
Consulte Emular Preparar para detalhes e exemplos. |
PDO::SQLSRV_ATTR_CURSOR_SCROLL_TYPE |
Especifica o tipo de cursor deslocável. Válido apenas quando PDO::ATTR_CURSOR estiver definido como PDO::CURSOR_SCROLL. Veja mais adiante neste artigo os valores que este atributo pode assumir. |
PDO::SQLSRV_ATTR_DECIMAL_PLACES |
Especifica o número de casas decimais ao formatar valores de moeda buscados. Esta opção só funciona quando PDO::SQLSRV_ATTR_FORMAT_DECIMALS é verdadeira. Para mais informações, consulte Formatação de Cadeias Decimais e Valores de Dinheiro (PDO_SQLSRV Driver). |
PDO::SQLSRV_ATTR_DIRECT_QUERY |
Quando True, especifica a execução direta da consulta.
False significa execução de instruções preparadas. Para mais informações sobre PDO::SQLSRV_ATTR_DIRECT_QUERY, consulte Execução Direta de Instruções e Execução de Instruções Preparadas no Driver PDO_SQLSRV. |
PDO::SQLSRV_ATTR_ENCODING |
PDO::SQLSRV_ENCODING_UTF8 (padrão)PDO::SQLSRV_ENCODING_UTF8_VARCHAR (versão 5.14.0 e posterior)PDO::SQLSRV_ENCODING_SYSTEMPDO::SQLSRV_ENCODING_BINARY |
PDO::SQLSRV_ATTR_FETCHES_DATETIME_TYPE |
Especifica se deve recuperar os tipos de data e hora como objetos PHP DateTime . Para mais informações, veja Como: Recuperar Tipos de Data e Hora como Objetos PHP DateTime usando o PDO_SQLSRV Driver. |
PDO::SQLSRV_ATTR_FETCHES_NUMERIC_TYPE |
Lida com buscas numéricas de colunas com tipos SQL numéricos. Para mais informações, veja PDO::setAttribute. |
PDO::SQLSRV_ATTR_FORMAT_DECIMALS |
Especifica se deve adicionar zeros à esquerda às cadeias decimais quando apropriado. Se definida, esta opção ativa a PDO::SQLSRV_ATTR_DECIMAL_PLACES opção de formatar tipos de moeda. Para mais informações, consulte Formatação de Cadeias Decimais e Valores de Dinheiro (PDO_SQLSRV Driver). |
PDO::SQLSRV_ATTR_QUERY_TIMEOUT |
Para mais informações, veja PDO::setAttribute. |
Ao utilizar PDO::ATTR_CURSOR => PDO::CURSOR_SCROLL, pode usar PDO::SQLSRV_ATTR_CURSOR_SCROLL_TYPE para especificar o tipo de cursor. Por exemplo, passe o seguinte array para PDO::prepare definir um cursor dinâmico:
array(PDO::ATTR_CURSOR => PDO::CURSOR_SCROLL, PDO::SQLSRV_ATTR_CURSOR_SCROLL_TYPE => PDO::SQLSRV_CURSOR_DYNAMIC));
A tabela seguinte mostra os valores possíveis para PDO::SQLSRV_ATTR_CURSOR_SCROLL_TYPE. Para mais informações sobre cursores desloçáveis, consulte Tipos de Cursor (PDO_SQLSRV Driver).
| valor | Description |
|---|---|
PDO::SQLSRV_CURSOR_BUFFERED |
Cria um cursor estático do lado do cliente (em buffer), que armazena o conjunto de resultados em memória na máquina cliente. |
PDO::SQLSRV_CURSOR_DYNAMIC |
Cria um cursor dinâmico do lado do servidor (sem buffer), que lhe permite aceder às linhas em qualquer ordem e refletir alterações na base de dados. |
PDO::SQLSRV_CURSOR_KEYSET |
Cria um cursor de conjunto de chaves do lado do servidor. Um cursor de conjunto de chaves não atualiza a contagem de linhas se uma linha for eliminada da tabela (uma linha eliminada é devolvida sem valores). |
PDO::SQLSRV_CURSOR_STATIC |
Cria um cursor estático do lado do servidor, que permite aceder às linhas em qualquer ordem, mas não reflete alterações na base de dados.PDO::ATTR_CURSOR => PDO::CURSOR_SCROLL implica PDO::SQLSRV_ATTR_CURSOR_SCROLL_TYPE => PDO::SQLSRV_CURSOR_STATIC. |
Pode fechar um PDOStatement objeto chamando unset:
unset($stmt);
Exemplo apenas de encaminhamento
Este exemplo mostra como usar PDO::prepare com marcadores de parâmetros e um cursor apenas para a frente.
<?php
$database = "Test";
$server = "(local)";
$conn = new PDO( "sqlsrv:server=$server ; Database = $database", "", "");
$col1 = 'a';
$col2 = 'b';
$query = "insert into Table1(col1, col2) values(?, ?)";
$stmt = $conn->prepare( $query, array( PDO::ATTR_CURSOR => PDO::CURSOR_FWDONLY, PDO::SQLSRV_ATTR_QUERY_TIMEOUT => 1 ) );
$stmt->execute( array( $col1, $col2 ) );
print $stmt->rowCount();
echo "\n";
$query = "insert into Table1(col1, col2) values(:col1, :col2)";
$stmt = $conn->prepare( $query, array( PDO::ATTR_CURSOR => PDO::CURSOR_FWDONLY, PDO::SQLSRV_ATTR_QUERY_TIMEOUT => 1 ) );
$stmt->execute( array( ':col1' => $col1, ':col2' => $col2 ) );
print $stmt->rowCount();
unset($stmt);
?>
Exemplo de cursor estático
Este exemplo mostra como usar PDO::prepare com um cursor estático do lado do servidor. Para um exemplo que mostra um cursor do lado do cliente, consulte Tipos de Cursor (PDO_SQLSRV Driver).
<?php
$database = "AdventureWorks";
$server = "(local)";
$conn = new PDO( "sqlsrv:server=$server ; Database = $database", "", "");
$query = "select * from Person.ContactType";
$stmt = $conn->prepare( $query, array(PDO::ATTR_CURSOR => PDO::CURSOR_SCROLL));
$stmt->execute();
echo "\n";
while ( $row = $stmt->fetch( PDO::FETCH_ASSOC ) ){
print "$row[Name]\n";
}
echo "\n..\n";
$row = $stmt->fetch( PDO::FETCH_BOTH, PDO::FETCH_ORI_FIRST );
print_r($row);
$row = $stmt->fetch( PDO::FETCH_ASSOC, PDO::FETCH_ORI_REL, 1 );
print "$row[Name]\n";
$row = $stmt->fetch( PDO::FETCH_NUM, PDO::FETCH_ORI_NEXT );
print "$row[1]\n";
$row = $stmt->fetch( PDO::FETCH_NUM, PDO::FETCH_ORI_PRIOR );
print "$row[1]..\n";
$row = $stmt->fetch( PDO::FETCH_NUM, PDO::FETCH_ORI_ABS, 0 );
print_r($row);
$row = $stmt->fetch( PDO::FETCH_NUM, PDO::FETCH_ORI_LAST );
print_r($row);
?>
Exemplo direcionado
Os dois excertos seguintes mostram como usar PDO::prepare com dados direcionados para colunas char / varchar . Como a codificação padrão para PDO::prepare é UTF-8, o utilizador pode usar essa opção PDO::SQLSRV_ENCODING_SYSTEM para evitar conversões implícitas.
Opção 1
$options = array(PDO::SQLSRV_ATTR_ENCODING => PDO::SQLSRV_ENCODING_SYSTEM);
$statement = $pdo->prepare(
'SELECT *
FROM myTable
WHERE myVarcharColumn = :myVarcharValue',
$options
);
$statement->bindValue(':myVarcharValue', 'my data', PDO::PARAM_STR);
Opção 2
$statement = $pdo->prepare(
'SELECT *
FROM myTable
WHERE myVarcharColumn = :myVarcharValue'
);
$p = 'my data';
$statement->bindParam(':myVarcharValue', $p, PDO::PARAM_STR, 0, PDO::SQLSRV_ENCODING_SYSTEM);
Preparar exemplo
Este exemplo mostra como usar PDO::p repare com PDO::ATTR_EMULATE_PREPARES o definido como true.
<?php
$serverName = "yourservername";
$username = "yourusername";
$password = "yourpassword";
$database = "tempdb";
$conn = new PDO("sqlsrv:server = $serverName; Database = $database", $username, $password);
$pdo_options = array();
$pdo_options[PDO::ATTR_EMULATE_PREPARES] = true;
$pdo_options[PDO::SQLSRV_ATTR_ENCODING] = PDO::SQLSRV_ENCODING_UTF8;
$stmt = $conn->prepare("CREATE TABLE TEST([id] [int] IDENTITY(1,1) NOT NULL,
[name] nvarchar(max))",
$pdo_options);
$stmt->execute();
$prefix = '가각';
$name = '가각ácasa';
$name2 = '가각sample2';
$stmt = $conn->prepare("INSERT INTO TEST(name) VALUES(:p0)", $pdo_options);
$stmt->execute(['p0' => $name]);
unset($stmt);
$stmt = $conn->prepare("SELECT * FROM TEST WHERE NAME LIKE :p0", $pdo_options);
$stmt->execute(['p0' => "$prefix%"]);
foreach ($stmt as $row) {
echo "\n" . 'FOUND: ' . $row['name'];
}
unset($stmt);
unset($conn);
?>
O PDO_SQLSRV controlador substitui internamente todos os marcadores de posição pelos parâmetros que estão ligados por PDOStatement::bindParam(). Portanto, uma cadeia de consulta SQL sem marcadores de posição é enviada para o servidor. Considere este exemplo:
$statement = $PDO->prepare("INSERT into Customers (CustomerName, ContactName) VALUES (:cus_name, :con_name)");
$statement->bindParam(:cus_name, "Cardinal");
$statement->bindParam(:con_name, "Tom B. Erichsen");
$statement->execute();
Com definido PDO::ATTR_EMULATE_PREPARES como false (o caso predefinido), os dados enviados para a base de dados são:
"INSERT into Customers (CustomerName, ContactName) VALUES (:cus_name, :con_name)"
Information on :cus_name parameter
Information on :con_name parameter
O servidor executa a consulta utilizando a sua funcionalidade de consulta parametrizada para parâmetros de ligação. Por outro lado, com PDO::ATTR_EMULATE_PREPARES definido como true, a consulta enviada ao servidor é essencialmente:
"INSERT into Customers (CustomerName, ContactName) VALUES ('Cardinal', 'Tom B. Erichsen')"
Definir PDO::ATTR_EMULATE_PREPARES como true pode contornar algumas restrições no SQL Server. Por exemplo, SQL Server não suporta parâmetros nomeados ou posicionais em algumas cláusulas Transact-SQL. Além disso, o SQL Server tem um limite de ligação de 2.100 parâmetros.
Note
Com o emulate prepares definido como true, a segurança das consultas parametrizadas não está em vigor. Portanto, a sua aplicação deve garantir que os dados vinculados aos parâmetros não contenham código Transact-SQL malicioso.
Codificação
Se o utilizador quiser ligar parâmetros com codificações diferentes (por exemplo, UTF-8 ou binário), deve especificar claramente a codificação no script PHP.
O PDO_SQLSRV driver verifica primeiro a codificação especificada em PDO::bindParam() (por exemplo, $statement->bindParam(:cus_name, "Cardinal", PDO::PARAM_STR, 10, PDO::SQLSRV_ENCODING_UTF8)).
Se não for encontrado, o driver verifica se alguma codificação está definida em PDO::prepare() ou PDOStatement::setAttribute(). Caso contrário, o driver utiliza a codificação especificada em PDO::__construct() ou PDO::setAttribute().
Além disso, a partir da versão 5.8.0, ao utilizar PDO::p repare com PDO::ATTR_EMULATE_PREPARES o valor definido como true, o utilizador pode usar os tipos de string estendidos introduzidos no PHP 7.2 para garantir que o N prefixo é utilizado. Os excertos seguintes mostram várias alternativas.
Note
Por predefinição, emulate prepares está definido como false, caso em que as constantes de string PDO estendidas serão ignoradas.
Use a opção de driver PDO::SQLSRV_ENCODING_UTF8 ao ligar
$p = '가각';
$sql = 'SELECT :value';
$options = array(PDO::ATTR_EMULATE_PREPARES => true);
$stmt = $conn->prepare($sql, $options);
$stmt->bindParam(':value', $p, PDO::PARAM_STR, 0, PDO::SQLSRV_ENCODING_UTF8);
$stmt->execute();
Utilize o atributo PDO::SQLSRV_ATTR_ENCODING
$p = '가각';
$sql = 'SELECT :value';
$options = array(PDO::ATTR_EMULATE_PREPARES => true, PDO::SQLSRV_ATTR_ENCODING => PDO::SQLSRV_ENCODING_UTF8);
$stmt = $conn->prepare($sql, $options);
$stmt->execute([':value' => $p]);
Use a constante PDO PDO::P ARAM_STR_NATL
$p = '가각';
$sql = 'SELECT :value';
$options = array(PDO::ATTR_EMULATE_PREPARES => true);
$stmt = $conn->prepare($sql, $options);
$stmt->bindParam(':value', $p, PDO::PARAM_STR | PDO::PARAM_STR_NATL);
$stmt->execute();
Defina o tipo de string param predefinido PDO::P ARAM_STR_NATL
$conn->setAttribute(PDO::ATTR_DEFAULT_STR_PARAM, PDO::PARAM_STR_NATL);
$p = '가각';
$sql = 'SELECT :value';
$options = array(PDO::ATTR_EMULATE_PREPARES => true);
$stmt = $conn->prepare($sql, $options);
$stmt->execute([':value' => $p]);
Limitations
Como pode ver, a ligação é feita internamente pelo driver. Uma consulta válida é enviada ao servidor para execução sem qualquer parâmetro. Comparado com o caso normal, surgem algumas limitações quando a funcionalidade de consulta parametrizada não está em uso.
- Não funciona para parâmetros ligados a
PDO::PARAM_INPUT_OUTPUT.- Quando o utilizador especifica
PDO::PARAM_INPUT_OUTPUTemPDO::bindParam(), é lançada uma exceção PDO.
- Quando o utilizador especifica
- Não funciona para parâmetros que estão ligados como parâmetros de saída.
- Quando o utilizador cria uma instrução preparada com marcadores de posição destinados a parâmetros de saída (isto é, tendo um sinal igual imediatamente após um marcador de posição, como
SELECT ? = COUNT(*) FROM Table1), é lançada uma exceção PDO. - Quando uma instrução preparada invoca um procedimento armazenado com um marcador de posição como argumento para um parâmetro de saída, não é lançada nenhuma exceção porque o driver não consegue detetar o parâmetro de saída. No entanto, a variável que o utilizador fornece para o parâmetro de saída permanece inalterada.
- Quando o utilizador cria uma instrução preparada com marcadores de posição destinados a parâmetros de saída (isto é, tendo um sinal igual imediatamente após um marcador de posição, como
- Reservatórios de posição duplicados para um parâmetro codificado binário não funcionam.