(PHP 5 >= 5.1.0, PHP 7, PECL pdo >= 0.1.0)
PDO::prepare — Prepara una sentencia para su ejecución y devuelve un objeto sentencia
Prepara una sentencia SQL para ser ejecutada por el método PDOStatement::execute(). La sentencia SQL puede contener cero o más marcadores de parámetros con nombre (:name) o signos de interrogación (?) por los cuales los valores reales serán sustituidos cuando la sentencia sea ejecutada. No se pueden usar marcadores de parámetros con nombre y signos de interrogación en la misma sentencia SQL; se debe elegir uno de los dos estilos de parámetros. Se deben usar estos parámetros para sustituir cualquier dato de usuario, y no usarlos directamente en la consulta.
Se debe incluir un único marcador de parámetro para cada valor que se desee pasar a la sentencia cuando se llame a PDOStatement::execute(). No se puede usar un marcador de parámetro con nombre con el mismo nombre más de una vez en una sentencia preparada, a menos que el modo de emulación esté activado.
Nota:
Los marcadores de parámetros solamente pueden representar un literal de datos completo. No se pueden vincular usando parámetros una parte del literal, ni una palabra clave, ni un identificador, ni ninguna parte arbitraria de una consulta. Por ejemplo, no se puede vincular valores múltiples a un único parámetro en la cláusula IN() de una sentencia SQL.
Llamar a PDO::prepare() y a PDOStatement::execute() para sentencias que serán ejecutadas en múltiples ocasiones con diferentes parámetros optimiza el rendimiento de la aplicación permitiendo al driver negociar en lado del cliente y/o servidor el almacenamiento en caché del plan de consulta y meta información, y ayuda a prevenir inyecciones SQL eliminando la necesidad de entrecomillar manualmente los parámetros.
PDO emulará sentencias preparadas/parámetros de sustitución para drivers que no lo soporten nativamente, y puede reescribir el estilo de los parámetros de sustitución por una forma más apropiada, si el driver soporta un estilo pero no el otro.
statementDebe ser una plantilla de sentencia SQL válida para el servidor de base de datos destino.
driver_optionsEste array guarda uno o más pares clave=>valor para establecer el valor de los atributos del objeto PDOStatement que este método devuelve. Comúnmente se establece el valor PDO::ATTR_CURSOR a PDO::CURSOR_SCROLL para solicitar el cursor desplazable. Algunos drivers tienen opciones específicas que pueden ser establecidas en el momento de la preparación.
Si el servidor de la base de datos prepara con éxito la sentencia,
PDO::prepare() devuelve un objeto PDOStatement.
Si no es posible, PDO::prepare() devuelve FALSE
o emite una excepciónPDOException (dependiendo del manejo de errores).
Nota:
Las sentencias preparadas emuladas no se comunican con el servidor de la base de datos con lo cual PDO::prepare() no comprueba la sentencia.
Ejemplo #1 Prepara una sentencia SQL con parámetros de sustitución nombrados
<?php
/* Ejecuta una sentencia preparada pasando un array de valores */
$sql = 'SELECT name, colour, calories
FROM fruit
WHERE calories < :calories AND colour = :colour';
$sth = $dbh->prepare($sql, array(PDO::ATTR_CURSOR => PDO::CURSOR_FWDONLY));
$sth->execute(array(':calories' => 150, ':colour' => 'red'));
$red = $sth->fetchAll();
$sth->execute(array(':calories' => 175, ':colour' => 'yellow'));
$yellow = $sth->fetchAll();
?>
Ejemplo #2 Prepara una sentencia SQL con parámetros de signos de interrogación
<?php
/* Ejecuta una sentencia preparada pasando un array de valores */
$sth = $dbh->prepare('SELECT name, colour, calories
FROM fruit
WHERE calories < ? AND colour = ?');
$sth->execute(array(150, 'red'));
$red = $sth->fetchAll();
$sth->execute(array(175, 'yellow'));
$yellow = $sth->fetchAll();
?>