character_set_name

Функция mysqli_character_set_name() возвращает набор символов по умолчанию, используемый для текущего соединения MySQLi — например utf8mb4, utf8 или latin1. На этой странице описывается, что возвращает функция, её синтаксис в обоих стилях, когда она может пригодиться и какие проблемы с кодировкой она помогает выявить.

Что контролирует набор символов

Набор символов соединения сообщает MySQL, как интерпретировать байты, которые вы отправляете (в операторах INSERT/UPDATE и параметрах запросов), и как кодировать байты, которые он возвращает. Если кодировка соединения не совпадает с фактической кодировкой ваших строк, возникает мойибакэ — испорченные символы с диакритикой, эмодзи превращаются в ????, и происходит незаметная потеря данных.

mysqli_character_set_name() — это самый быстрый способ проверить это значение во время выполнения. Функция предназначена только для чтения диагностической информации: она ничего не изменяет. Чтобы изменить кодировку, используйте set_charset().

Синтаксис

Функция имеет объектно-ориентированную и процедурную форму. Они эквивалентны — выбирайте ту, которая соответствует стилю вашего кода.

// Object-oriented style
string $mysqli->character_set_name()

// Procedural style
string mysqli_character_set_name(mysqli $mysqli)

• Параметр (только для процедурного стиля): $mysqli — соединение, возвращённое функцией mysqli_connect() или new mysqli().
• Возвращаемое значение: string с именем текущего набора символов (например, "utf8mb4"). Функция не возвращает false; при действительном соединении набор символов всегда определён.

Как использовать mysqli_character_set_name()

Вызовите функцию на открытом соединении и выведите результат:

<?php
$mysqli = new mysqli("localhost", "your_username", "your_password", "database");
if ($mysqli->connect_errno) {
    echo "Failed to connect to MySQL: " . $mysqli->connect_error;
    exit();
}

echo "Character set: " . $mysqli->character_set_name();

$mysqli->close();
?>

Типичный вывод до явной установки кодировки — это значение по умолчанию для сервера:

Character set: utf8mb4

То же самое в процедурном стиле:

<?php
$mysqli = mysqli_connect("localhost", "your_username", "your_password", "database");
if (mysqli_connect_errno()) {
    echo "Failed to connect to MySQL: " . mysqli_connect_error();
    exit();
}

echo "Character set: " . mysqli_character_set_name($mysqli);

mysqli_close($mysqli);
?>

Чтение кодировки после её изменения

Поскольку функция отображает текущее значение, она удобна для подтверждения того, что вызов set_charset() действительно вступил в силу:

<?php
$mysqli = new mysqli("localhost", "your_username", "your_password", "database");
if ($mysqli->connect_errno) {
    echo "Failed to connect to MySQL: " . $mysqli->connect_error;
    exit();
}

echo "Before: " . $mysqli->character_set_name() . "\n";

$mysqli->set_charset("utf8mb4");
echo "After:  " . $mysqli->character_set_name() . "\n";

$mysqli->close();
?>

Before: latin1
After:  utf8mb4

Почему нужно устанавливать кодировку, а не только читать её

mysqli_character_set_name() лишь сообщает о кодировке — она не может её исправить. Для полной поддержки Unicode (включая эмодзи и многие символы CJK) устанавливайте utf8mb4 сразу после подключения:

<?php
$mysqli = new mysqli("localhost", "your_username", "your_password", "database");
if ($mysqli->connect_errno) {
    echo "Failed to connect to MySQL: " . $mysqli->connect_error;
    exit();
}

$mysqli->set_charset("utf8mb4");
$mysqli->query("INSERT INTO users (name, email) VALUES ('Jörg 🚀', '[email protected]')");

$mysqli->close();
?>

Примечания и подводные камни:

• Предпочитайте utf8mb4, а не utf8. Устаревший utf8 в MySQL — это 3-байтовый псевдоним, который не может хранить 4-байтовые символы, такие как эмодзи. utf8mb4 — это настоящий полноценный UTF-8.
• Не используйте SET NAMES ... в виде запроса для смены кодировки. Это обновляет серверную сессию, но клиентская библиотека об этом не знает, что нарушает работу real_escape_string(). Всегда используйте set_charset(), чтобы оба компонента оставались синхронизированы.
• Возвращаемое имя — это кодировка соединения, которая не зависит от кодировки столбца или таблицы, определённой в схеме.

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

• mysqli_set_charset() — изменить кодировку соединения.
• mysqli_get_charset() — получить полный объект с описанием кодировки (сопоставление, длина байта и другое).
• mysqli_connect_errno() / mysqli_connect_error() — обнаружить ошибки соединения до чтения кодировки.
• Обзор PHP MySQLi — расширение MySQLi в целом.

Заключение

mysqli_character_set_name() — это небольшая, надёжная диагностическая функция для проверки того, какой набор символов используется в соединении MySQL. Используйте её для отладки проблем с кодировкой, а для их устранения вызывайте set_charset("utf8mb4"), чтобы ваше приложение корректно сохраняло текст с диакритикой и эмодзи.

Практика