Guia Completo sobre a Função mysqli_set_charset em PHP

Quando você armazena nomes, comentários ou emoji no MySQL, os bytes só fazem o percurso de ida e volta corretamente se o PHP e o banco de dados concordarem com um conjunto de caracteres — o mapeamento entre bytes e caracteres. A função mysqli_set_charset define o conjunto de caracteres para a conexão entre seu script PHP e o servidor MySQL, para que tudo que você envia e recebe seja interpretado da mesma forma em ambos os lados.

Esta página explica o que a função faz, por que definir o charset na conexão é importante (e por que também é uma medida de segurança), e como usá-la com as APIs mysqli procedural e orientada a objetos.

O que mysqli_set_charset faz

mysqli_set_charset informa ao servidor MySQL qual conjunto de caracteres o cliente (seu script PHP) usará pelo restante da conexão. Isso afeta como as strings de consulta são interpretadas, como os resultados são codificados no retorno e quais bytes mysqli_real_escape_string() trata como especiais.

A assinatura procedural recebe primeiro a conexão e depois o nome do charset, e retorna true em caso de sucesso ou false em caso de falha:

mysqli_set_charset(mysqli $connection, string $charset): bool

A forma orientada a objetos é um método no objeto de conexão:

$connection->set_charset($charset);

O argumento $charset é um nome de conjunto de caracteres MySQL como utf8mb4, utf8 ou latin1 — não um nome de codificação PHP. Use utf8mb4 para suporte completo a Unicode, incluindo caracteres de 4 bytes como emoji; o alias mais antigo utf8 no MySQL armazena apenas até 3 bytes por caractere e não suporta emoji.

Defina na conexão, não apenas nas consultas. Executar SET NAMES utf8mb4 como uma consulta altera o charset no lado do servidor, mas não atualiza o valor que a biblioteca cliente C usa para escapar. mysqli_set_charset atualiza ambos, razão pela qual é a forma correta e segura de trocar charsets.

Conectando e definindo o charset

mysqli_set_charset precisa de uma conexão existente, portanto primeiro abra uma com mysqli_connect. O exemplo abaixo conecta e imediatamente define utf8mb4:

<?php

$host     = 'localhost';
$user     = 'username';
$password = 'password';
$database = 'mydatabase';

$connection = mysqli_connect($host, $user, $password, $database);

if (!$connection) {
    die('Connection failed: ' . mysqli_connect_error());
}

if (!mysqli_set_charset($connection, 'utf8mb4')) {
    die('Error setting charset: ' . mysqli_error($connection));
}

echo 'Current charset: ' . mysqli_character_set_name($connection);
// Current charset: utf8mb4

Após a chamada ser bem-sucedida, mysqli_character_set_name informa o charset ativo, confirmando que a alteração entrou em vigor.

Exemplo orientado a objetos

Se você usa a API mysqli orientada a objetos, chame set_charset() como método. É uma boa prática fazer isso logo após construir a conexão, antes de executar qualquer consulta:

<?php

$mysqli = new mysqli('localhost', 'username', 'password', 'mydatabase');

if ($mysqli->connect_errno) {
    die('Connection failed: ' . $mysqli->connect_error);
}

if (!$mysqli->set_charset('utf8mb4')) {
    die('Error setting charset: ' . $mysqli->error);
}

echo $mysqli->character_set_name();
// utf8mb4

Tratando falhas

mysqli_set_charset retorna false se o servidor não suportar o charset solicitado (por exemplo, um erro de digitação como utf8mb44). Sempre verifique o valor de retorno em vez de assumir sucesso:

<?php

if (!mysqli_set_charset($connection, 'utf8mb4')) {
    // Log it and stop — running queries with the wrong charset
    // can corrupt stored text and weaken escaping.
    throw new RuntimeException(
        'Failed to set charset: ' . mysqli_error($connection)
    );
}

Você pode chamar a função mais de uma vez na mesma conexão para trocar charsets durante a sessão, embora na prática você a defina uma vez logo após conectar e a deixe assim.

Por que isso é importante

• Texto correto. Sem um charset correspondente, letras acentuadas e scripts não latinos voltam como ? ou mojibake (caracteres embaralhados como é em vez de é).
• Emoji e Unicode completo. Apenas utf8mb4 armazena caracteres de 4 bytes; utf8 os descarta ou trunca silenciosamente.
• Segurança. mysqli_real_escape_string() faz o escape com base no charset da conexão. Definir corretamente fecha uma classe de vetores de injeção SQL que exploram incompatibilidades de bytes multibyte. Mesmo assim, prefira instruções preparadas em vez de escape manual.

Funções relacionadas

• mysqli_connect — abre a conexão que você passa para set_charset.
• mysqli_get_charset — obtém um objeto completo descrevendo o charset atual (collation, comentário, número).
• mysqli_character_set_name — obtém apenas o nome do charset ativo.
• mysqli_select_db — troca o banco de dados ativo em uma conexão existente.

Conclusão

mysqli_set_charset alinha o conjunto de caracteres do seu script PHP com sua conexão MySQL, garantindo que o texto percorra o caminho de ida e volta corretamente e que o escaping se comporte com segurança. Defina como utf8mb4 logo após conectar, verifique o valor de retorno e você terá coberto os casos comuns — de nomes acentuados a emoji.

Prática