PDO::prepare
(PHP 5 >= 5.1.0, PHP 7, PHP 8, PHP 8,PECL pdo >= 0.1.0)
PDO::prepare —
Подготавливает запрос к выполнению и возвращает связанный с этим запросом
объект
Описание
public PDO::prepare(
string $query
,
array $options
= []):
PDOStatement|false
Вы должны подбирать уникальные имена псевдопеременных для каждого значения,
которое необходимо передавать в запрос при вызове
PDOStatement::execute(). Нельзя использовать одну псевдопеременную
в запросе более одного раза, кроме варианта, когда включён режим эмуляции.
Замечание:
Псевдопеременные должны представлять только единичный объем данных.
Не часть значения, ни служебное слово, ни имя поля, ни какую либо произвольную
часть запроса. К примеру, вы не можете связать псевдопеременную с несколькими
значениями для вставки в конструкцию IN().
Вызов PDO::prepare() и
PDOStatement::execute() для запросов, которые будут
запускаться многократно с различными параметрами, повышает производительность
приложения, позволяя драйверу кешировать на клиенте и/или сервере
план выполнения запроса и метаданные, а также помогает избежать SQL-инъекций,
так как нет необходимости экранировать передаваемые параметры.
Если драйвер не поддерживает подготавливаемые запросы, PDO умеет их эмулировать, а
также может заменять псевдопеременные на то, что больше подходит, если, например,
драйвер поддерживает только именованные или, наоборот, только неименованные псевдопеременные.
Замечание:
Синтаксический анализатор, используемый для эмулируемых подготовленных операторов
и для перезаписи именованных параметров или параметров стиля вопросительного знака, поддерживает нестандартные
обратные слеши для одинарных и двойных кавычек. Это означает, что завершающие
кавычки, непосредственно предшествующие обратной косой черте, не распознаются как таковые, что
может привести к неправильному обнаружению параметров, что приведёт к сбою подготовленного оператора
при его выполнении. Обходной путь — не использовать эмулированную подготовку к таким
SQL-запросам и избегать перезаписи параметров, используя стиль параметров,
который изначально поддерживается драйвером.
Список параметров
-
query
-
Это должен быть корректный SQL-запрос с точки зрения целевой СУБД.
-
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() - Запускает подготовленный запрос на выполнение