PHPTime

MySQLi в PHP: подключение и запросы к MySQL

MySQLi — расширение PHP для работы с MySQL. Оно открывает соединение, выполняет запросы и возвращает результаты. На примерах разберём подключение, чтение и запись данных, транзакции и различия между версиями PHP 8.x.

PHP и MySQLi: какое расширение использовать

Для подключения PHP к MySQL подходят MySQLi и PDO с драйвером pdo_mysql. MySQLi рассчитано на MySQL и предоставляет объектный и процедурный интерфейсы. Например, $db->query($sql) и mysqli_query($db, $sql) выполняют одну и ту же операцию. Дальше используется объектный интерфейс.

В старых примерах PHP и MySQL встречаются функции mysql_connect() и mysql_query() из удалённого расширения ext/mysql. Для современного кода используйте new mysqli() для подключения, query() для фиксированного SQL и prepare() для запросов с параметрами.

Проверить наличие расширения в CLI можно командой php --ri mysqli. Если ошибка возникает только на сайте, проверьте расширение в окружении веб-приложения. PHP-FPM и CLI могут читать разные конфигурационные файлы.

Как подключить PHP к MySQL через MySQLi

Вынесите создание соединения в отдельный файл. В примере db.php читает настройки из окружения и возвращает готовый объект mysqli. Задайте DB_USER, DB_PASSWORD и DB_NAME в окружении процесса PHP. Хост и порт по умолчанию подходят для локального сервера с TCP-подключением.

PHP
<?php
declare(strict_types=1);

mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);

$user = getenv('DB_USER');
$password = getenv('DB_PASSWORD');
$database = getenv('DB_NAME');

if ($user === false || $password === false || $database === false) {
    throw new RuntimeException('Не заданы настройки подключения к MySQL');
}

// 127.0.0.1 открывает TCP-соединение с локальным сервером.
$db = new mysqli(
    getenv('DB_HOST') ?: '127.0.0.1',
    $user,
    $password,
    $database,
    (int) (getenv('DB_PORT') ?: '3306')
);
$db->set_charset('utf8mb4');

return $db;

На Unix-подобных системах значение localhost обычно выбирает Unix-сокет. Для TCP используйте IP-адрес или имя хоста сервера. Если PHP и MySQL работают в разных контейнерах, укажите сетевое имя сервиса MySQL. Адрес 127.0.0.1 внутри контейнера PHP указывает на сам этот контейнер.

set_charset('utf8mb4') задаёт кодировку обмена данными на соединении. Для хранения эмодзи и других символов за пределами базовой плоскости Unicode у текстовых столбцов тоже должна быть подходящая кодировка. declare(strict_types=1) задаёт строгий режим для скалярных объявлений типов в PHP. Типы параметров SQL задаются отдельно при выполнении запроса.

Таблица для примеров

Выполните этот SQL один раз в базе, указанной в DB_NAME. Примеры ниже предполагают, что db.php лежит рядом с запускаемым скриптом.

SQL
CREATE TABLE users (
    id INT UNSIGNED NOT NULL AUTO_INCREMENT PRIMARY KEY,
    email VARCHAR(254) NOT NULL UNIQUE,
    name VARCHAR(100) NOT NULL
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

SELECT в PHP: получить строки из MySQL

Для фиксированного запроса без внешних параметров вызовите query(). Для SELECT метод возвращает объект mysqli_result. fetch_assoc() читает одну строку как ассоциативный массив, а после последней строки возвращает null.

PHP
<?php
declare(strict_types=1);

$db = require __DIR__ . '/db.php';
$result = $db->query('SELECT id, name FROM users ORDER BY id LIMIT 20');

// Экранируем имя при выводе в HTML.
while ($row = $result->fetch_assoc()) {
    printf("<p>%d. %s</p>\n", (int) $row['id'],
        htmlspecialchars($row['name'], ENT_QUOTES | ENT_SUBSTITUTE, 'UTF-8'));
}
$result->free();

Для небольшой выборки удобно взять все строки через fetch_all(MYSQLI_ASSOC). По умолчанию query() буферизует результат целиком, поэтому построчный цикл сам по себе не ограничивает память на больших выборках. Для выгрузок используйте порции или query($sql, MYSQLI_USE_RESULT). При небyферизованном чтении дочитайте результат либо освободите его перед следующим запросом на том же соединении.

В запросах с JOIN задавайте псевдонимы одноимённым столбцам, например users.id AS user_id. Иначе при чтении через fetch_assoc() значение последнего столбца с таким именем перезапишет предыдущее.

Подготовленные запросы MySQLi: параметры, INSERT и поиск

Передавайте внешние значения отдельно от SQL. Подготовленный запрос использует маркеры ?, а bind_param() связывает их с переменными по порядку. Строка типов содержит по одному символу на параметр. i означает целое число, d — число с плавающей точкой, s — строку, b — двоичные данные, которые можно отправлять частями через send_long_data().

PHP
<?php
declare(strict_types=1);

$db = require __DIR__ . '/db.php';
$email = 'anna@example.test';
$name = 'Анна';

// При повторном запуске этот email вызовет ошибку UNIQUE.
$stmt = $db->prepare('INSERT INTO users (email, name) VALUES (?, ?)');
$stmt->bind_param('ss', $email, $name);
$stmt->execute();
$id = $db->insert_id;
$stmt->close();

printf("Создан пользователь с ID %s\n", (string) $id);

bind_param() принимает переменные по ссылке. Если нужно вставить несколько записей, подготовьте запрос и привяжите переменные один раз, затем присваивайте им новые значения перед каждым execute(). Для разового запроса можно передать массив непосредственно в $stmt->execute([$email, $name]). В этой форме параметры передаются как строки. Если тип параметра важен, задайте его через bind_param().

SELECT с параметром

В PHP 8.3–8.5 метод execute_query() объединяет подготовку, передачу параметров и выполнение. Для SELECT он возвращает mysqli_result. Метод доступен при сборке с mysqlnd, как и get_result() у объекта mysqli_stmt.

PHP
<?php
declare(strict_types=1);

$db = require __DIR__ . '/db.php';
$email = 'anna@example.test';

// Значение email передаётся отдельно от SQL.
$result = $db->execute_query(
    'SELECT id, name FROM users WHERE email = ?',
    [$email]
);
$user = $result->fetch_assoc();
$result->free();

if ($user === null) {
    echo 'Пользователь не найден';
}

Для сборки без mysqlnd используйте prepare(), bind_param() и execute(), затем привяжите столбцы через $stmt->bind_result($id, $name) и прочитайте строку через $stmt->fetch(). После каждого успешного чтения значения появятся в привязанных переменных.

Маркеры ? представляют значения. Для выбора столбца сортировки или направления ASC/DESC сопоставьте входной параметр с заранее заданными фрагментами SQL. Для IN (...) создайте по одному маркеру на элемент списка. При пустом списке верните пустой результат до запроса.

UPDATE, DELETE и транзакции

Запросы INSERT, UPDATE и DELETE возвращают признак успеха. Число затронутых строк доступно в $stmt->affected_rows после выполнения подготовленного запроса или в $db->affected_rows после запроса через соединение. Для UPDATE при настройках по умолчанию ноль может означать, что строка не найдена или новое значение совпало со старым. Для DELETE ноль означает, что запрос ничего не удалил.

Если группа изменений должна примениться целиком, используйте транзакцию на одном соединении. Для примера с InnoDB ниже обе вставки сохранятся после commit(). Если один из адресов уже занят, rollback() отменит изменения текущей транзакции.

PHP
<?php
declare(strict_types=1);

$db = require __DIR__ . '/db.php';
$stmt = $db->prepare('INSERT INTO users (email, name) VALUES (?, ?)');
$email = $name = '';
$stmt->bind_param('ss', $email, $name);

$db->begin_transaction();
try {
    foreach (['oleg@example.test' => 'Олег', 'ira@example.test' => 'Ира'] as $address => $displayName) {
        // execute() читает текущие значения привязанных переменных.
        $email = $address;
        $name = $displayName;
        $stmt->execute();
    }
    $db->commit();
} catch (Throwable $error) {
    $db->rollback();
    throw $error;
} finally {
    $stmt->close();
}

Команды изменения схемы, например ALTER TABLE, могут вызвать неявный COMMIT в MySQL. Выполняйте миграции отдельно от транзакций приложения. В обычном коротком PHP-запросе соединение закрывается при завершении скрипта. В долгоживущем процессе освобождайте результаты и закрывайте соединение явно, когда оно больше не нужно.

Типичные ошибки MySQLi и различия PHP 8.x

СимптомЧто проверить
Class "mysqli" not foundПодключено ли расширение mysqli в том окружении, где работает скрипт.
Access denied for userИмя пользователя, пароль и учётную запись MySQL для адреса, с которого приходит соединение. У приложения должны быть права на нужную базу.
Connection refused или No such file or directory при подключенииВ первом случае проверьте хост, порт и доступность TCP. Во втором при локальном подключении проверьте путь к сокету.
Commands out of syncДочитайте или освободите небyферизованный результат. После вызова процедуры проверьте, остались ли дополнительные наборы результатов.
Duplicate entryОпределите, какое ограничение уникальности сработало. Если конфликт ожидаем, обработайте код MySQL 1062 на уровне операции.

При включённом строгом режиме MySQLi ошибки запросов и подключения приводят к mysqli_sql_exception. В приложении обрабатывайте ожидаемые ошибки там, где известен контекст операции. Остальные передавайте общему обработчику. В закрытом журнале обычно достаточно контекста операции и кода ошибки. Пользователю возвращайте понятное сообщение без SQL, параметров и реквизитов подключения.

  • PHP 8.1. Режим MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT стал стандартным для MySQLi. Явная настройка в файле подключения делает поведение понятным при чтении кода.
  • PHP 8.2. Появился mysqli::execute_query(), поэтому его можно использовать во всех трёх версиях от PHP 8.3 до 8.5.
  • PHP 8.3–8.5. Для подключения, параметров и транзакций подходит один и тот же код. При переносе старого проекта учтите, что mysqli::ping() и mysqli::kill() объявлены устаревшими с PHP 8.4. Для явной проверки соединения выполните SELECT 1 и обработайте исключение. Обычное завершение соединения выполняется через close().

Чек-лист перед запуском

  1. Убедитесь, что веб-приложение загружает mysqli. Если используете execute_query() или get_result(), проверьте наличие mysqlnd.
  2. Передайте настройки из окружения, проверьте хост и способ подключения. Выдайте учётной записи приложения права на операции, которые ей нужны.
  3. Задайте utf8mb4 на соединении и проверьте кодировку столбцов. Для вывода строк в HTML используйте htmlspecialchars().
  4. Все внешние значения передавайте параметрами. Имена столбцов и направление сортировки выбирайте из разрешённых вариантов.
  5. Проверьте пустую выборку, конфликт уникальности и откат при сбое внутри транзакции. Для больших результатов проверьте расход памяти на реальном объёме данных.

Частые вопросы

Как проверить, установлено ли MySQLi в PHP?

В командной строке выполните php --ri mysqli. Для сайта проверяйте extension_loaded('mysqli') в окружении веб-приложения, поскольку CLI и PHP-FPM могут использовать разные конфигурации.

Чем заменить mysql_query() в PHP 8?

Для фиксированного SQL используйте mysqli::query(). Для запроса с внешними значениями используйте prepare() и execute() либо execute_query() в сборке с mysqlnd.

Почему UPDATE прошёл успешно, а affected_rows равен нулю?

По умолчанию MySQL считает изменённые строки. Ноль означает, что условие WHERE не нашло строк или найденные строки уже содержали указанные значения.

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

Ещё в разделе «Справочник PHP»

Ассоциативные и многомерные массивы в PHP

Как создавать ассоциативные и многомерные массивы в PHP, читать вложенные данные, получать ключи и значения через array_keys() и array_values().

10 мин

Вывод ошибок в PHP: display_errors, error_reporting и логи

Как включить вывод ошибок PHP через display_errors и ini_set, настроить error_reporting и error_log, найти логи и разобраться с deprecated в PHP 8.3–8.5.

9 мин

Дата и время в PHP: date, DateTime и часовые пояса

Как получить текущую дату и время в PHP, настроить часовой пояс, разобрать строку и отформатировать дату с date(), strtotime() и DateTimeImmutable.

8 мин

Загрузка файлов на сервер в PHP: $_FILES и безопасность

Как принять файл через $_FILES, проверить размер, MIME-тип и расширение, сохранить его вне публичной папки, выдать на скачивание и обработать ZIP.

10 мин