Подготавливает запрос к выполнению и возвращает ассоциированный с этим запросом объект


(PHP 5 >= 5.1.0, PECL pdo >= 0.1.0)

PDO::prepare Подготавливает запрос к выполнению и возвращает ассоциированный с этим запросом объект

Описание

public PDOStatement PDO::prepare ( string $statement [, array $driver_options = array() ] )

Подготавливает SQL запрос к базе данных к запуску посредством метода PDOStatement::execute(). Запрос может содержать именованные (:name) или неименованные (?) псевдопеременные, которые будут заменены реальными значениями во время запуска запроса на выполнение. Использовать одновременно и именованные, и неименованные псевдопеременные в одном запросе нельзя, необходимо выбрать что-то одно. Используйте псевдопеременные, чтобы привязать к запросу пользовательский ввод, не включайте данные, введенные пользователем, напрямую в запрос.

Вы должны подбирать уникальные имена псевдопеременных для каждого значение, которое необходимо передавать в запрос при вызове PDOStatement::execute(). Нельзя использовать одну псевдопеременную в запросе больше одного раза, если только не включен режим эмуляции.

Замечание:

Маркеры параметров представляют из себя только непосредственно данные. Ни часть данных, ни специальные слова, ни идентификаторы, никакая другая часть запроса не могут быть переданы через параметры. Например, вы не можете привязать несколько значений к одному параметру для SQL выражения IN().

Вызов PDO::prepare() и PDOStatement::execute() для запросов, которые будут запускаться многократно с различными параметрами, повышает производительность приложения, так как позволяет драйверу кэшировать на клиенте и/или сервере план выполнения запроса и метаданные, а также помогает избежать SQL иньекций, так как нет необходимости экранировать передаваемые параметры.

Если драйвер не поддерживает подготавливаемые запросы, PDO умеет их эмулировать. Также, PDO может заменять псевдопеременные на то, что больше подходит, если, например, драйвер поддерживает только именованные или, наоборот, только неименованные маркеры.

Список параметров

statement

Это должен быть корректный запрос с точки зрения целевой СУБД.

driver_options

Этот массив содержит одну или более пар ключ=>значение для установки значений атрибутов объекта PDOStatement, который будет возвращен из этого метода. В основном, вы будете использовать этот массив для присвоения значения PDO::ATTR_CURSOR атрибуту PDO::CURSOR_SCROLL, чтобы получить прокручиваемый курсор. У некоторых драйверов могут быть свои специфические настройки, которые можно задать во время подготовки запроса.

Возвращаемые значения

Если СУБД успешно подготовила запрос, PDO::prepare() возвращает объект PDOStatement. Если подготовить запрос не удалось, PDO::prepare() возвращает FALSE или выбрасывает исключение PDOException (зависит от текущего режима обработки ошибок).

Замечание:

Эмулируемые подготовленные запросы не создаются на сервере баз данных, поэтому PDO::prepare() не может проверить правильность построенного запроса.

Примеры

Пример #1 Подготовка SQL запроса с именованными параметрами

<?php
/* Выполнение запроса с передачей ему массива параметров */
$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();
?>

Пример #2 Подготовка SQL запроса с неименованными параметрами (?)

<?php
/* Выполнение запроса с передачей ему массива параметров */
$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();
?>

Смотрите также

  • PDO::exec() - Запускает SQL запрос на выполнение и возвращает количество строк, задействованых в ходе его выполнения
  • PDO::query() - Выполняет SQL запрос и возвращает результирующий набор в виде объекта PDOStatement
  • PDOStatement::execute() - Запускает подготовленный запрос на выполнение