array ( 0 => 'index.php', 1 => 'PHP Manual', ), 'head' => array ( 0 => 'UTF-8', 1 => 'ru', ), 'this' => array ( 0 => 'pdo.prepare.php', 1 => 'PDO::prepare', 2 => 'Подготавливает запрос к выполнению и возвращает связанный с этим запросом объект', ), 'up' => array ( 0 => 'class.pdo.php', 1 => 'PDO', ), 'prev' => array ( 0 => 'pdo.lastinsertid.php', 1 => 'PDO::lastInsertId', ), 'next' => array ( 0 => 'pdo.query.php', 1 => 'PDO::query', ), 'alternatives' => array ( ), 'source' => array ( 'lang' => 'ru', 'path' => 'reference/pdo/pdo/prepare.xml', ), 'history' => array ( ), ); $setup["toc"] = $TOC; $setup["toc_deprecated"] = $TOC_DEPRECATED; $setup["parents"] = $PARENTS; manual_setup($setup); contributors($setup); ?>

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

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

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

Замечание:

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

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

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

Замечание: Синтаксический анализатор, используемый для эмулируемых подготовленных операторов и для перезаписи именованных параметров или параметров стиля вопросительного знака, поддерживает нестандартные обратные слеши для одинарных и двойных кавычек. Это означает, что завершающие кавычки, непосредственно предшествующие обратной косой черте, не распознаются как таковые, что может привести к неправильному обнаружению параметров, что приведёт к сбою подготовленного оператора при его выполнении. Обходной путь — не использовать эмулированную подготовку к таким SQL-запросам и избегать перезаписи параметров, используя стиль параметров, который изначально поддерживается драйвером.

Начиная с PHP 7.4.0, можно избежать экранирования вопросительных знаков, удвоив их. Это означает, что строка ?? будет преобразована в ? при отправке запроса в базу данных.

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

query

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

options

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

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

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

Замечание:

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

Ошибки

Метод выдаёт ошибку уровня E_WARNING, если для атрибута PDO::ATTR_ERRMODE установили режим PDO::ERRMODE_WARNING.

Метод выбрасывает исключение PDOException, если для атрибута PDO::ATTR_ERRMODE установили режим PDO::ERRMODE_EXCEPTION.

Примеры

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

<?php
/* Выполнение запроса с передачей ему массива параметров */
$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();
/* Ключи массива также могут начинаться с двоеточия ":" (необязательно) */
$sth->execute([':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([150, 'red']);
$red = $sth->fetchAll();
$sth->execute([175, 'yellow']);
$yellow = $sth->fetchAll();
?>

Пример #3 Подготовка SQL-запроса с экранированным вопросительным знаком

<?php
/* замечание: работает только с базами данных PostgreSQL */
$sth = $dbh->prepare('SELECT * FROM issues WHERE tag::jsonb ?? ?');
$sth->execute(['feature']);
$featureIssues = $sth->fetchAll();
$sth->execute(['performance']);
$performanceIssues = $sth->fetchAll();
?>

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