mysqli_options()

Функция mysqli_options() задаёт дополнительные параметры подключения, определяющие, как PHP взаимодействует с MySQL. В этом руководстве объясняется, что делает каждый распространённый параметр, строгое правило о том, когда его можно вызывать, и как объединить его с mysqli_real_connect() в реальной последовательности подключения.

Введение в функцию mysqli_options()

mysqli_options() настраивает поведение дескриптора подключения MySQLi до открытия соединения. Это процедурный эквивалент объектно-ориентированного метода mysqli::options().

Ключевое, что нужно понять, — это порядок операций. Обычный вызов mysqli_connect() одновременно создаёт дескриптор и подключается за один шаг, не оставляя возможности задать параметры. Чтобы использовать mysqli_options(), необходимо разделить эти два шага:

1. Создать неподключённый дескриптор с помощью mysqli_init().
2. Задать один или несколько параметров с помощью mysqli_options().
3. Открыть фактическое подключение с помощью mysqli_real_connect().

Установка параметра после того, как соединение уже открыто, либо не имеет эффекта, либо завершается ошибкой — в зависимости от параметра.

Синтаксис

mysqli_options(mysqli $mysql, int $option, mixed $value): bool

• $mysql — дескриптор подключения, возвращённый mysqli_init() (ещё не подключённый).
• $option — одна из констант параметров MYSQLI_* (см. ниже).
• $value — значение для данного параметра; ожидаемый тип зависит от параметра.

Функция возвращает true при успехе и false при ошибке.

Часто используемые константы параметров

Как использовать функцию mysqli_options()

Пример ниже инициализирует дескриптор, задаёт тайм-аут подключения и включает загрузку локальных файлов, а затем открывает соединение:

<?php
$mysqli = mysqli_init();

/* Set connection timeout to 10 seconds */
mysqli_options($mysqli, MYSQLI_OPT_CONNECT_TIMEOUT, 10);

/* Enable LOAD DATA LOCAL INFILE */
mysqli_options($mysqli, MYSQLI_OPT_LOCAL_INFILE, 1);

/* Now open the actual connection */
if (!mysqli_real_connect($mysqli, "localhost", "username", "password", "database")) {
    die("Connection failed: " . mysqli_connect_error());
}

echo "Connected successfully";
?>

Здесь мы сначала создаём неподключённый дескриптор с помощью mysqli_init(), настраиваем тайм-аут и поведение с локальными файлами через mysqli_options(), и только после этого подключаемся с помощью mysqli_real_connect(). Результат подключения проверяется с помощью mysqli_connect_error(), которая возвращает описание последней ошибки подключения.

Выполнение команды сразу после подключения

MYSQLI_INIT_COMMAND удобен, когда каждое соединение должно начинаться в известном состоянии — например, для принудительной установки набора символов сессии или часового пояса. Оператор выполняется после каждого подключения и переподключения:

<?php
$mysqli = mysqli_init();

mysqli_options($mysqli, MYSQLI_INIT_COMMAND, "SET NAMES 'utf8mb4'");

if (!mysqli_real_connect($mysqli, "localhost", "username", "password", "database")) {
    die("Connection failed: " . mysqli_connect_error());
}
?>

Распространённые ошибки

• Вызывайте до подключения. Это наиболее частая ошибка. Используйте mysqli_init() + mysqli_options() + mysqli_real_connect(), но никогда не используйте обычный mysqli_connect().
• SSL — отдельно. Пути к сертификату, ключу и CA настраиваются с помощью mysqli_ssl_set(), а не mysqli_options().
• MYSQLI_OPT_LOCAL_INFILE — это настройка безопасности. Включайте её только если вам действительно нужен LOAD DATA LOCAL INFILE; включение может позволить скомпрометированному серверу читать локальные файлы.
• Проверяйте возвращаемое значение. mysqli_options() возвращает false для неподдерживаемых параметров, поэтому стоит проверять это, когда параметр молча не работает.

Заключение

mysqli_options() позволяет точно настроить подключение MySQLi — тайм-ауты, загрузку локальных файлов и команды при запуске — но только в рамках последовательности mysqli_init() → mysqli_options() → mysqli_real_connect(). Для продолжения работы с подключениями MySQLi смотрите mysqli_connect() и как диагностировать ошибки с помощью mysqli_connect_error().

Практика