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

public PDO::prepare(string $query, array $options = []): PDOStatement|false

Prepara uma instrução SQL para ser executada pelo método PDOStatement::execute(). O modelo de instrução pode conter zero ou mais marcadores de parâmetros nomeados (:name) ou pontos de interrogação (?) para os quais os valores reais serão substituídos quando a instrução for executada. Os marcadores de parâmetros nomeados e de ponto de interrogação não podem ser usados no mesmo modelo de instrução; apenas um ou outro estilo de parâmetro. Use esses parâmetros para vincular qualquer entrada do usuário, não inclua a entrada do usuário diretamente na consulta.

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.

Erros/Exceções

Emite um erro de nível E_WARNING se o atributo PDO::ATTR_ERRMODE estiver definido como PDO::ERRMODE_WARNING.

Lança uma exceção PDOException se o atributo PDO::ATTR_ERRMODE estiver definido como PDO::ERRMODE_EXCEPTION.

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

Veja Também

PDO::exec() - Executa uma instrução SQL e retorna o número de linhas afetadas
PDO::query() - Prepara e executa uma instrução SQL sem marcadores
PDOStatement::execute() - Executa ums instrução preparada