PDO::prepare

Descarregar o driver PHP

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 Observações.

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_SYSTEM
PDO::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_OUTPUT em PDO::bindParam(), é lançada uma exceção PDO.
  • 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.
  • Reservatórios de posição duplicados para um parâmetro codificado binário não funcionam.