PDO::prepare

Baixar o driver PHP

Prepara uma instrução para execução.

Sintaxe

PDOStatement PDO::prepare ( $statement [ , array(key_pair) ] )

Parâmetros

$instrução

uma cadeia de caracteres que contém a instrução SQL.

key_pair

uma matriz que contém um nome e valor de atributo. Para obter mais informações, consulte a seção Comentários.

Valor retornado

Retorna um PDOStatement objeto em caso de êxito. Em caso de falha, retorna um PDOException objeto ou false, dependendo do valor de PDO::ATTR_ERRMODE.

Comentários

Os Drivers da Microsoft para PHP para SQL Server não avaliam instruções preparadas até a execução.

A tabela a seguir mostra os valores possíveis de key_pair.

Ao usar PDO::ATTR_CURSOR => PDO::CURSOR_SCROLL, use PDO::SQLSRV_ATTR_CURSOR_SCROLL_TYPE para especificar o tipo de cursor. Por exemplo, passe a seguinte matriz para PDO::prepare para definir um cursor dinâmico:

array(PDO::ATTR_CURSOR => PDO::CURSOR_SCROLL, PDO::SQLSRV_ATTR_CURSOR_SCROLL_TYPE => PDO::SQLSRV_CURSOR_DYNAMIC));

A tabela a seguir mostra os valores possíveis para PDO::SQLSRV_ATTR_CURSOR_SCROLL_TYPE. Para saber mais sobre os cursores de rolagem, confira Tipos de cursor (PDO_SQLSRV Driver).

Você pode fechar um PDOStatement objeto chamando unset:

unset($stmt);

Exemplo de somente avanço

Este exemplo mostra como usar PDO::prepare com marcadores de parâmetro e um cursor somente para 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 ver um exemplo que mostra um cursor do lado do cliente, confira 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 snippets a seguir mostram como usar PDO::prepare com dados direcionados para colunas char / varchar. Como a codificação padrão é PDO::prepare UTF-8, o usuário pode usar a 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);

Exemplo com prepare

Este exemplo mostra como usar o método PDO::prepare com PDO::ATTR_EMULATE_PREPARES 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 driver substitui internamente todos os espaços reservados pelos parâmetros associados a PDOStatement::bindParam(). Portanto, uma cadeia de caracteres de consulta SQL sem espaços reservados é enviada ao 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 PDO::ATTR_EMULATE_PREPARES definido como false (o caso padrão), os dados enviados para o banco 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 usando seu recurso de consulta parametrizada para parâmetros de associaçã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 ignorar algumas restrições no SQL Server. Por exemplo, o SQL Server não dá suporte a parâmetros nomeados ou posicionais em algumas cláusulas Transact-SQL. Além disso, o SQL Server tem um limite de 2.100 parâmetros.

Codificação

Se o usuário deseja associar parâmetros com diferentes codificações (por exemplo, UTF-8 ou binária), ele deve especificar claramente a codificação no script PHP.

O PDO_SQLSRV driver primeiro verifica 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 encontrado, o driver verifica se alguma codificação está definida em PDO::prepare() ou PDOStatement::setAttribute(). Caso contrário, o driver usará a codificação especificada em PDO::__construct() ou PDO::setAttribute().

Além disso, a partir da versão 5.8.0, ao usar PDO::p repare com PDO::ATTR_EMULATE_PREPARES set to true, o usuário pode usar os tipos de string estendida introduzidos no PHP 7.2 para garantir que o prefixo N seja usado. Os snippets a seguir exibem várias alternativas.

Usar a opção de driver PDO::SQLSRV_ENCODING_UTF8 ao associar

$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();

Use 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 parâmetro de string padrão 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]);

Limitações

Como você pode ver, a associação é feita internamente pelo driver. Uma consulta válida é enviada ao servidor para execução sem nenhum parâmetro. Em comparação com o caso normal, algumas limitações resultam quando o recurso de consulta parametrizada não está em uso.

• Não funciona para parâmetros vinculados como PDO::PARAM_INPUT_OUTPUT.
  • Quando o usuário especifica PDO::PARAM_INPUT_OUTPUT em PDO::bindParam(), ocorre uma exceção de PDO.
• Ele não funciona para parâmetros associados como parâmetros de saída.
  • Quando o usuário cria uma instrução preparada com espaços reservados que servem para parâmetros de saída (ou seja, ter um sinal de igual imediatamente após um espaço reservado, como SELECT ? = COUNT(*) FROM Table1), ocorre uma exceção de PDO.
  • Quando uma instrução preparada invoca um procedimento armazenado com um espaço reservado como argumento para um parâmetro de saída, nenhuma exceção é gerada porque o driver não pode detectar o parâmetro de saída. No entanto, a variável que o usuário fornece para o parâmetro de saída permanece inalterada.
• Espaços reservados duplicados para um parâmetro codificado binário não funcionam.

Conteúdo relacionado

• PDO Class
• PDO