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-запиту з іменованими параметрами
Приклад #2 Підготовка SQL-запиту з неназваними параметрами (символ '?')
Приклад #3 Підготовка SQL-запиту з екранованим знаком питання
Дивіться також
- PDO::exec() - Виконує SQL-запит та повертає кількість порушених рядків
- PDO::query() - готує та виконує вираз SQL без заповнювачів
- PDOStatement::execute() - Запускає підготовлений запит на виконання