character_set_name

A função mysqli_character_set_name() retorna o conjunto de caracteres padrão em uso para a conexão MySQLi atual — por exemplo utf8mb4, utf8 ou latin1. Esta página explica o que a função retorna, sua sintaxe nos dois estilos, quando utilizá-la e os problemas de codificação que ela ajuda a identificar.

O que o conjunto de caracteres controla

O conjunto de caracteres da conexão diz ao MySQL como interpretar os bytes que você envia (em instruções INSERT/UPDATE e parâmetros de consulta) e como codificar os bytes que ele devolve. Se o charset da conexão não corresponder à codificação real das suas strings, você obterá mojibake — letras acentuadas corrompidas, emojis transformados em ???? e perda silenciosa de dados.

mysqli_character_set_name() é a maneira mais rápida de inspecionar essa configuração em tempo de execução. É um diagnóstico somente leitura: nunca altera nada. Para alterar o charset, use set_charset().

Sintaxe

A função possui uma forma orientada a objetos e uma forma procedural. Elas são equivalentes — escolha a que melhor se encaixa no seu código.

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

// Procedural style
string mysqli_character_set_name(mysqli $mysqli)

• Parâmetro (apenas procedural): $mysqli — uma conexão retornada por mysqli_connect() ou new mysqli().
• Valor de retorno: uma string com o nome do conjunto de caracteres atual (ex.: "utf8mb4"). Ela não retorna false; em uma conexão válida, sempre há um charset.

Como usar mysqli_character_set_name()

Chame-a em uma conexão aberta e exiba o resultado:

<?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();
?>

Uma saída típica, antes de definir qualquer coisa explicitamente, é o padrão do servidor:

Character set: utf8mb4

O mesmo em estilo procedural:

<?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);
?>

Lendo o charset após alterá-lo

Como a função reporta a configuração atual, ela é útil para confirmar que uma chamada a set_charset() realmente teve efeito:

<?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

Por que você deve definir o charset, não apenas lê-lo

mysqli_character_set_name() apenas reporta o charset — não pode corrigi-lo. Para suporte completo a Unicode (incluindo emojis e muitos caracteres CJK), defina utf8mb4 logo após conectar:

<?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();
?>

Notas e armadilhas:

• Prefira utf8mb4 em vez de utf8. O utf8 legado do MySQL é um alias de 3 bytes que não consegue armazenar caracteres de 4 bytes, como emojis. utf8mb4 é o UTF-8 real e completo.
• Não execute SET NAMES ... como uma consulta para alterar o charset. Isso atualiza a sessão no lado do servidor, mas deixa a biblioteca cliente sem saber, o que quebra real_escape_string(). Use sempre set_charset() para que ambos permaneçam sincronizados.
• O nome retornado é o charset da conexão, que é independente do charset de uma coluna ou tabela definido no schema.

Funções relacionadas

• mysqli_set_charset() — altera o conjunto de caracteres da conexão.
• mysqli_get_charset() — obtém um objeto completo descrevendo o charset (collation, tamanho em bytes e mais).
• mysqli_connect_errno() / mysqli_connect_error() — detecta falhas de conexão antes de ler o charset.
• Visão geral do PHP MySQLi — a extensão MySQLi de forma mais ampla.

Conclusão

mysqli_character_set_name() é um diagnóstico pequeno e confiável para confirmar qual conjunto de caracteres uma conexão MySQL está usando. Leia-o para depurar problemas de codificação e, em seguida, corrija-os com set_charset("utf8mb4") para que sua aplicação armazene textos acentuados e emojis corretamente.

Prática