(PHP 5 >= 5.1.0, PHP 7, PHP 8, PHP 8,PECL pdo >= 0.1.0)
PDO::prepare — Prepara una consulta para su ejecución y devuelve un objeto
Prepara una consulta SQL para ser ejecutada por el método
PDOStatement::execute(). El modelo de declaración puede contener
cero o más parámetros nombrados (:nombre
) o marcadores
(?
) para los cuales los valores reales serán sustituidos
cuando la consulta sea ejecutada.
El uso tanto de parámetros nombrados como de marcadores es
imposible en un modelo de declaración; solo uno u otro estilo de parámetro.
Utilícese estos parámetros para ligar las entradas del usuario, no se incluyan
directamente en la consulta.
Debe incluirse un marcador con un nombre único para cada valor que se desee pasar en la consulta al llamar a PDOStatement::execute(). No puede utilizarse un marcador con dos nombres idénticos en una consulta preparada, a menos que el modo de emulación esté activo.
Nota:
Los marcadores de parámetros pueden representar únicamente un literal de datos completo. Ni una parte de literal, ni una palabra clave, ni un identificador, ni cualquier otra consulta arbitraria pueden ser ligados utilizando los parámetros. Por ejemplo, no puede asociarse múltiples valores a un solo marcador de nombre entrante, en la cláusula IN() de una consulta SQL.
Llamar a PDO::prepare() y PDOStatement::execute() para las consultas que deben ser ejecutadas varias veces con diferentes valores de parámetros optimiza el rendimiento de la aplicación permitiendo al controlador negociar del lado del cliente y/o servidor con la caché de consultas y las meta-informaciones. Además, llamar a PDO::prepare() y PDOStatement::execute() ayuda a prevenir ataques por inyección SQL eliminando la necesidad de proteger los parámetros manualmente.
PDO emula las consultas preparadas / los parámetros ligados para los controladores que no los soportan nativamente, y puede también reescribir los parámetros nombrados o los marcadores en algo más apropiado, si el controlador soporta un estilo y no el otro.
Nota: El analizador utilizado para las declaraciones preparadas emuladas y para reescribir los parámetros nombrados o del estilo de punto de interrogación soporta el escape antislash no estándar para las comillas simples y dobles. Esto significa que las comillas finales que son precedidas por un antislash no serán reconocidas como tales, lo que puede resultar en una mala detección de los parámetros causando que la declaración preparada falle al ser ejecutada. Un contorno es no utilizar las consultas emuladas para tales consultas SQL, y evitar reescribir los parámetros utilizando un estilo de parámetro que es soportado nativamente por el controlador.
A partir de PHP 7.4.0, los puntos de interrogación pueden ser escapados duplicándolos.
Esto significa que la cadena ??
será traducida en ?
al enviar la consulta a la base de datos.
query
Debe ser un modelo de consulta SQL válido para el servidor de base de datos objetivo.
options
Este array contiene una o más parejas clave=>valor para definir
los valores de los atributos para el objeto PDOStatement
que esta método devuelve. Puede utilizarse esto para definir el valor
PDO::ATTR_CURSOR
a
PDO::CURSOR_SCROLL
para solicitar un cursor desplazable.
Algunos controladores tienen opciones específicas que pueden ser definidas
en el momento de la preparación.
Si el servidor de base de datos prepara con éxito esta consulta,
PDO::prepare() devuelve un objeto PDOStatement.
Si el servidor de base de datos no logra preparar la consulta,
PDO::prepare() devuelve false
o emite una excepción
PDOException (siguiendo el
gestor de errores).
Nota:
La emulación de consultas preparadas no comunica con el servidor de base de datos. También, la función PDO::prepare() no verifica la consulta.
Emits an error with level E_WARNING
if the attribute PDO::ATTR_ERRMODE
is set
to PDO::ERRMODE_WARNING
.
Throws a PDOException if the attribute PDO::ATTR_ERRMODE
is set to PDO::ERRMODE_EXCEPTION
.
Ejemplo #1 Modelo de declaración SQL con parámetros nombrados
<?php
/* Ejecuta una consulta preparada pasando un array de valores */
$sql = 'SELECT nombre, color, calorias
FROM fruta
WHERE calorias < :calorias AND color = :color';
$sth = $dbh->prepare($sql, [PDO::ATTR_CURSOR => PDO::CURSOR_FWDONLY]);
$sth->execute(['calorias' => 150, 'color' => 'red']);
$red = $sth->fetchAll();
/* Las claves del array pueden ser prefijadas con dos puntos ":" también (opcional) */
$sth->execute([':calorias' => 175, ':color' => 'yellow']);
$yellow = $sth->fetchAll();
?>
Ejemplo #2 Modelo de declaración SQL con marcadores
<?php
/* Ejecuta una consulta preparada pasando un array de valores */
$sth = $dbh->prepare('SELECT nombre, color, calorias
FROM fruta
WHERE calorias < ? AND color = ?');
$sth->execute([150, 'rojo']);
$red = $sth->fetchAll();
$sth->execute([175, 'amarillo']);
$yellow = $sth->fetchAll();
?>
Ejemplo #3 Modelo de declaración SQL con un punto de interrogación escapado
<?php
/* nota: esto solo es válido para bases de datos PostgreSQL */
$sth = $dbh->prepare('SELECT * FROM issues WHERE tag::jsonb ?? ?');
$sth->execute(['feature']);
$featureIssues = $sth->fetchAll();
$sth->execute(['performance']);
$performanceIssues = $sth->fetchAll();
?>