mysqli::query

mysqli_query

(PHP 5, PHP 7, PHP 8)

mysqli::query -- mysqli_query — Выполняет запрос к базе данных

Описание

Объектно-ориентированный стиль

public function mysqli::query(string $query, int $result_mode = MYSQLI_STORE_RESULT): mysqli_result|bool

Процедурный стиль

function mysqli_query(mysqli $mysql, string $query, int $result_mode = MYSQLI_STORE_RESULT): mysqli_result|bool

Выполняет запрос query к базе данных.

Внимание

Предупреждение безопасности: SQL-инъекция

Вместо составления строки запроса с включением переменных значений необходимо подготавливать запросы. Либо строки запроса должны быть экранированы функцией mysqli_real_escape_string() и правильно отформатированы.

Для не DML-запросов (не INSERT, UPDATE или DELETE), эта функция равносильна вызову функции mysqli_real_query(), а затем mysqli_use_result() или mysqli_store_result().

Замечание:

Если длина передаваемого в функцию mysqli_query() выражения больше значения системной переменной max_allowed_packet сервера, будет сгенерирована ошибка. MySQL-драйвер (mysqlnd) и клиентская библиотека MySQL (libmysqlclient) выбрасывают разные коды ошибок. Поведение функции будет следующим:

  • mysqlnd на платформе Linux возвращает код ошибки 1153. Сообщение об ошибке означает размер пакета превышает max_allowed_packet байт.

  • mysqlnd на платформе Windows возвращает код ошибки 2006. Это сообщение об ошибке означает отказ сервера.

  • libmysqlclient на всех платформах возвращает код ошибки 2006. Это сообщение об ошибке означает отказ сервера.

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

mysql
Только для процедурного стиля: объект mysqli, который вернула функция mysqli_connect() или функция mysqli_init().
query

Текст запроса.

result_mode

Режим результата может быть одной из 3 констант, указывающих, как результат будет возвращён сервером MySQL.

MYSQLI_STORE_RESULT (по умолчанию) — возвращает объект mysqli_result с буферизованным набором результатов.

MYSQLI_USE_RESULT — возвращает объект mysqli_result с небуферизованным набором результатов. Пока есть отложенные записи, ожидающие выборки, линия соединения будет занята и все последующие вызовы будут возвращать ошибку Commands out of sync. Чтобы избежать ошибки, все записи должны быть получены с сервера или набор результатов должен быть отброшен путём вызова mysqli_free_result().

MYSQLI_ASYNC (доступно с mysqlnd) — запрос выполняется асинхронно, набор результатов сразу не возвращается. Затем вызывают функцию mysqli_poll() для получения результатов по этим запросам. Можно использовать в сочетании с константой MYSQLI_STORE_RESULT или MYSQLI_USE_RESULT.

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

Возвращает false в случае возникновения ошибки. В случае успешного выполнения запросов, которые создают набор результатов, таких как SELECT, SHOW, DESCRIBE или EXPLAIN, функция mysqli_query() вернёт объект mysqli_result. Для остальных успешных запросов mysqli_query() вернёт true.

Ошибки

Если уведомления об ошибках mysqli включены (MYSQLI_REPORT_ERROR) и запрошенная операция не удалась, выдаётся предупреждение. Если, кроме того, установлен режим MYSQLI_REPORT_STRICT, вместо этого будет выброшено исключение mysqli_sql_exception.

Примеры

Пример #1 Пример использования mysqli::query()

Объектно-ориентированный стиль

<?php

mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
$mysqli = new mysqli("localhost", "my_user", "my_password", "world");

/* Создание таблицы, не возвращает набор результатов */
$mysqli->query("CREATE TEMPORARY TABLE myCity LIKE City");
printf("Таблица myCity создана.\n");

/* Запросы SELECT, возвращают набор результатов */
$result = $mysqli->query("SELECT Name FROM City LIMIT 10");
printf("Запрос SELECT вернул %d строк.\n", $result->num_rows);

/* Если нужно извлечь большой объем данных, используем MYSQLI_USE_RESULT */
$result = $mysqli->query("SELECT * FROM City", MYSQLI_USE_RESULT);

/* Важно заметить, что мы не можем вызывать функции, которые взаимодействуют
с сервером, пока не закроем набор результатов. Все подобные вызовы
будут вызывать ошибку 'out of sync' */
$mysqli->query("SET @a:='this will not work'");

Процедурный стиль

<?php

mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
$link = mysqli_connect("localhost", "my_user", "my_password", "world");

/* Создание таблицы, не возвращает набор результатов */
mysqli_query($link, "CREATE TEMPORARY TABLE myCity LIKE City");
printf("Таблица myCity создана.\n");

/* Запросы SELECT, возвращают набор результатов */
$result = mysqli_query($link, "SELECT Name FROM City LIMIT 10");
printf("Запрос SELECT вернул %d строк.\n", mysqli_num_rows($result));

/* Если нужно извлечь большой объем данных, используем MYSQLI_USE_RESULT */
$result = mysqli_query($link, "SELECT * FROM City", MYSQLI_USE_RESULT);

/* Важно заметить, что мы не можем вызывать функции, которые взаимодействуют
с сервером, пока не закроем набор результатов. Все подобные вызовы
будут вызывать ошибку 'out of sync' */
mysqli_query($link, "SET @a:='this will not work'");

Результат выполнения приведённых примеров: 

Таблица myCity создана.
Запрос SELECT вернул 10 строк.

Fatal error: Uncaught mysqli_sql_exception: Commands out of sync; you can't run this command now in...

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

  • mysqli_execute_query() - Подготавливает, связывает параметры и выполняет SQL-запрос
  • mysqli_real_query() - Выполнение SQL запроса
  • mysqli_multi_query() - Выполняет запросы к базе данных
  • mysqli_prepare() - Подготавливает SQL выражение к выполнению
  • mysqli_free_result() - Освобождает память, занятую результатами запроса