PDO::prepare
(PHP 5 >= 5.1.0, PHP 7, PHP 8, PHP 8,PECL pdo >= 0.1.0)
PDO::prepare —
Prepara uma instrução para execução e retorna um objeto de instrução
Descrição
Deve-se incluir um marcador de parâmetro exclusivo para cada valor que se deseja passar
para a instrução ao chamar PDOStatement::execute().
Um marcador de parâmetro nomeado com o mesmo nome não pode ser usado mais de uma vez em uma instrução
preparada, a menos que o modo de emulação esteja ativado.
Nota:
Os marcadores de parâmetro podem representar apenas um literal de dados completo.
Nem parte do literal, nem palavra-chave, nem identificador, nem qualquer parte arbitrária
da consulta podem ser vinculadas usando parâmetros. Por exemplo, não se pode vincular múltiplos valores
a um único parâmetro na cláusula IN() de uma instrução SQL.
Chamar PDO::prepare() e
PDOStatement::execute() para instruções que serão
emitidas diversas vezes com valores de parâmetros diferentes otimiza o
desempenho da aplicação, permitindo que o driver negocie
cache no lado do cliente e/ou do servidor do plano de consulta e metainformações. Além disso, chamar PDO::prepare() e
PDOStatement::execute() ajuda a evitar ataques de injeção de SQL, eliminando a necessidade de
inserir aspas e escapar manualmente dos parâmetros.
O PDO irá emular instruções preparadas/parâmetros vinculados para drivers que
não os suportam nativamente, e também pode reescrever marcadores de parâmetros nomeados
ou no estilo ponto de interrogação para algo mais apropriado, se o driver
suportar um estilo, mas não o outro.
Nota:
O analisador usado para instruções preparadas emuladas e para
reescrever parâmetros nomeados ou no estilo de ponto de interrogação suporta escapes
de barra invertida não padrão para aspas simples e duplas. Isso significa que aspas
de término imediatamente precedidas por uma barra invertida não são reconhecidas como tal, o que
pode resultar na detecção incorreta de parâmetros, fazendo com que a instrução preparada
falhe quando for executada. Uma solução alternativa é não usar preparações emuladas para
essas consultas SQL e evitar a reescrita de parâmetros usando um estilo de parâmetro
que seja suportado nativamente pelo driver.
A partir do PHP 7.4.0, os pontos de interrogação podem ser escapados duplicando-os. Isso significa que
a string ?? será traduzida para ?
ao enviar a consulta ao banco de dados.
Parâmetros
query-
Este deve ser um modelo de instrução SQL válido para o servidor de banco de dados de destino.
options-
Este array contém um ou mais pares chave=>valor para definir
valores de atributos para o objeto PDOStatement que esse método
retorna. Normalmente usa-se isso para definir o
valor PDO::ATTR_CURSOR como
PDO::CURSOR_SCROLL para solicitar um cursor rolável.
Alguns drivers têm opções específicas que podem ser definidas no
momento da preparação.
Valor Retornado
Se o servidor de banco de dados preparar a instrução com sucesso,
PDO::prepare() retornará um
objeto PDOStatement.
Se o servidor de banco de dados não conseguir preparar a instrução com sucesso,
PDO::prepare() retornará false ou emitirá
uma exceção PDOException (dependendo do tratamento de erros).
Nota:
Instruções preparadas emuladas não se comunicam com o servidor de banco de dados,
portanto PDO::prepare() não verifica a instrução.
Exemplos
Exemplo #1 Modelo de instrução SQL com parâmetros nomeados
<?php
/* Executa uma instrução preparada passando um array de valores */
$sql = 'SELECT name, colour, calories
FROM fruit
WHERE calories < :calories AND colour = :colour';
$sth = $dbh->prepare($sql, [PDO::ATTR_CURSOR => PDO::CURSOR_FWDONLY]);
$sth->execute(['calories' => 150, 'colour' => 'red']);
$red = $sth->fetchAll();
/* Chaves de arrays podem ser prefizadas com dois-pontos ":" também (opcional) */
$sth->execute([':calories' => 175, ':colour' => 'yellow']);
$yellow = $sth->fetchAll();
?>
Exemplo #2 Modelo de instrução SQL com parâmetros de ponto de interrogação
<?php
/* Executa uma instrução preparada passando um array de valores */
$sth = $dbh->prepare('SELECT name, colour, calories
FROM fruit
WHERE calories < ? AND colour = ?');
$sth->execute([150, 'red']);
$red = $sth->fetchAll();
$sth->execute([175, 'yellow']);
$yellow = $sth->fetchAll();
?>
Exemplo #3 Modelo de instrução SQL com ponto de interrogação escapado
<?php
/* nota: isso só é válido em bancos de dados PostgreSQL */
$sth = $dbh->prepare('SELECT * FROM issues WHERE tag::jsonb ?? ?');
$sth->execute(['feature']);
$featureIssues = $sth->fetchAll();
$sth->execute(['performance']);
$performanceIssues = $sth->fetchAll();
?>
