init

Функция mysqli_init() выделяет и инициализирует объект MySQLi без открытия соединения с базой данных. Это первый шаг двухэтапного процесса подключения: вы создаёте объект, настраиваете его низкоуровневые параметры и только после этого подключаетесь с помощью mysqli_real_connect(). На этой странице объясняется синтаксис, возвращаемое значение, когда именно она нужна и типичные ошибки, которые допускают разработчики.

Синтаксис

mysqli_init(): mysqli|false

В объектно-ориентированном стиле отдельного метода нет — new mysqli() (вызванный без аргументов) выполняет ту же инициализацию:

$mysqli = mysqli_init();   // procedural
$mysqli = new mysqli();    // object-oriented equivalent

• Параметры: отсутствуют.
• Возвращаемое значение: новый, неподключённый объект mysqli в случае успеха или false при ошибке. (Начиная с PHP 8.1 процедурная форма является лишь псевдонимом new mysqli() и при ошибке бросает исключение вместо возврата false, в зависимости от настроек mysqli_report().)

Зачем существует mysqli_init()

Когда вы вызываете new mysqli("localhost", "user", "pass", "db") с аргументами, PHP инициализирует объект и устанавливает соединение в один шаг. Это удобно, но не оставляет возможности настроить параметры, которые должны быть заданы до рукопожатия — таймауты соединения, начальная команда SET NAMES, SSL или поддержка local-infile.

mysqli_init() разделяет эти два этапа:

1. Инициализировать объект с помощью mysqli_init().
2. Настроить его с помощью mysqli_options() (и SSL через mysqli_ssl_set() при необходимости).
3. Подключиться с помощью mysqli_real_connect().

Если предварительная настройка параметров не нужна, mysqli_init() можно полностью пропустить и передать учётные данные напрямую в new mysqli() — это короче и не менее правильно.

Базовый пример

Ниже показан канонический процедурный рабочий процесс. Обратите внимание, что mysqli_options() вызывается между init и connect:

<?php
$mysqli = mysqli_init();

if (!$mysqli) {
    die("mysqli_init() failed");
}

// Run on every new connection — must be set before connecting.
mysqli_options($mysqli, MYSQLI_INIT_COMMAND, "SET NAMES 'utf8mb4'");

// Give up after 5 seconds instead of hanging.
mysqli_options($mysqli, MYSQLI_OPT_CONNECT_TIMEOUT, 5);

if (!mysqli_real_connect($mysqli, "localhost", "username", "password", "database")) {
    echo "Failed to connect to MySQL: " . mysqli_connect_error();
    exit;
}

echo "Connected. Server version: " . mysqli_get_server_info($mysqli);

mysqli_close($mysqli);
?>

Порядок действий: создать объект, задать параметры, которые должны предшествовать рукопожатию, затем подключиться. Мы проверяем результат mysqli_real_connect() и читаем причину ошибки с помощью mysqli_connect_error(). Наконец, mysqli_close() освобождает соединение.

Важно: параметры, переданные в mysqli_options(), вступают в силу только если они заданы до mysqli_real_connect(). Вызов после подключения не даёт никакого эффекта.

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

Та же программа в стиле ООП — более наглядна в современных проектах:

<?php
$mysqli = new mysqli();   // unconnected, same as mysqli_init()

$mysqli->options(MYSQLI_INIT_COMMAND, "SET NAMES 'utf8mb4'");
$mysqli->options(MYSQLI_OPT_CONNECT_TIMEOUT, 5);

if (!$mysqli->real_connect("localhost", "username", "password", "database")) {
    echo "Failed to connect: " . $mysqli->connect_error;
    exit;
}

echo "Connected. Server version: " . $mysqli->server_info;
$mysqli->close();
?>

Распространённые предварительные параметры

Несколько параметров, которые обычно задают после mysqli_init():

Для TLS настройте параметры с помощью mysqli_ssl_set() (см. mysqli_ssl_set()) перед вызовом mysqli_real_connect().

Типичные ошибки

• Она не устанавливает соединение. Дескриптор, полученный от mysqli_init(), непригоден для выполнения запросов до тех пор, пока mysqli_real_connect() не завершится успехом.
• Порядок имеет значение. Все предварительные параметры должны быть заданы до подключения, иначе они молча игнорируются.
• Предпочтительнее использовать set_charset() для кодировки. Использование MYSQLI_INIT_COMMAND с SET NAMES работает, но mysqli_set_charset() (вызванный после подключения) является рекомендуемым способом задать кодировку соединения, поскольку клиентская библиотека также должна знать кодировку для корректного экранирования.

Связанные функции

• mysqli_real_connect() — открывает соединение на инициализированном объекте.
• mysqli_options() — задаёт предварительные параметры соединения.
• mysqli_connect_errno() / mysqli_connect_error() — проверка ошибок подключения.
• Обзор расширения mysqli — как все части работают вместе.

Заключение

mysqli_init() предназначена для одной задачи: получить неподключённый объект MySQLi, чтобы настроить низкоуровневые параметры до рукопожатия. Если такие параметры не нужны, более простым вариантом является new mysqli(...) с учётными данными. Обращайтесь к mysqli_init(), когда нужен таймаут соединения, init-команда или SSL — тогда последовательность mysqli_options() → mysqli_real_connect() завершает процесс.

Практика