get_charset

A função mysqli_get_charset() retorna o conjunto de caracteres que o PHP está usando para uma determinada conexão MySQL — por exemplo, utf8mb4, latin1 ou utf8. Conhecer o charset ativo é importante porque ele controla como o texto é codificado entre o PHP e o MySQL: o charset errado transforma letras acentuadas, emojis e scripts não-latinos em "mojibake" ilegível, sendo uma fonte clássica de caracteres ? nos dados armazenados.

Este artigo explica o que a função retorna, como ler cada campo do resultado e as razões práticas para chamá-la.

Sintaxe

mysqli_get_charset(mysqli $mysql): ?object

No estilo orientado a objetos, a mesma função está disponível como o método $mysqli->get_charset().

• $mysql — uma conexão retornada por mysqli_connect().
• Valor de retorno — um object stdClass descrevendo o conjunto de caracteres da conexão, ou null se o charset não puder ser determinado.

O que o object retornado contém

Ao contrário de funções que retornam uma string simples, mysqli_get_charset() retorna um object com vários campos. Os mais úteis são:

Uso básico

Chame a função em uma conexão válida e leia a propriedade charset:

<?php
$mysqli = mysqli_connect("localhost", "username", "password", "database");

if (mysqli_connect_errno()) {
    die("Connection failed: " . mysqli_connect_error());
}

$charset = mysqli_get_charset($mysqli);

printf("Character set: %s\n", $charset->charset);   // e.g. utf8mb4
printf("Collation:     %s\n", $charset->collation); // e.g. utf8mb4_general_ci

mysqli_close($mysqli);
?>

Conectamos com mysqli_connect(), verificamos se há erro de conexão e, em seguida, lemos os campos charset e collation do object retornado.

Estilo orientado a objetos

Se você preferir a API OOP mysqli, use o método get_charset():

<?php
$mysqli = new mysqli("localhost", "username", "password", "database");

$charset = $mysqli->get_charset();

echo "Charset:   {$charset->charset}\n";
echo "Max bytes: {$charset->max_length}\n"; // 4 for utf8mb4

$mysqli->close();
?>

Quando usaria isso?

• Depurando bugs de codificação. Quando o texto armazenado aparece como ? ou símbolos corrompidos, confirmar o charset da conexão é o primeiro passo de diagnóstico.
• Verificando se uma chamada a set_charset() teve efeito. Após chamar mysqli_set_charset(), você pode lê-lo de volta para ter certeza de que a alteração foi aplicada.
• Ramificando com base na largura de bytes. Ler max_length indica se a conexão pode armazenar caracteres de 4 bytes, como emojis (utf8mb4), ou apenas até 3 bytes (utf8).

Obter apenas o nome

Se você precisar apenas do nome do charset e não do object completo, mysqli_character_set_name() o retorna diretamente como uma string:

<?php
$mysqli = new mysqli("localhost", "username", "password", "database");

echo $mysqli->character_set_name(); // e.g. utf8mb4

$mysqli->close();
?>

Armadilhas comuns

• Não confunda com a variável character_set_client do MySQL. Esta função reporta o charset que o PHP está usando para se comunicar com o servidor; ela não altera como as colunas armazenam dados — isso é definido pela definição da tabela/coluna.
• Defina o charset explicitamente. Depender do padrão do servidor é frágil entre hosts. Chame mysqli_set_charset($mysqli, "utf8mb4") logo após conectar; então mysqli_get_charset() deve reportar utf8mb4.
• Acessando propriedades em null. Se a conexão falhar, a função pode retornar null; ler ->charset em null gera um aviso. Sempre verifique a conexão primeiro.

Conclusão

mysqli_get_charset() retorna um object descrevendo o conjunto de caracteres de uma conexão MySQLi — seu nome, collation e limites de bytes. Use-a para diagnosticar problemas de codificação e confirmar que mysqli_set_charset() foi aplicada conforme esperado. Para obter apenas o nome, use mysqli_character_set_name().

Prática