PDO::prepare

Descrição

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.

Note:

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.

Note: 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.

<?php
/* Executa uma instrução preparada passando uma matriz 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();
?>

<?php
/* Executa uma instrução preparada passando uma matriz 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();
?>

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