character_set_name

La fonction mysqli_character_set_name() retourne le jeu de caractères par défaut utilisé pour la connexion MySQLi en cours — par exemple utf8mb4, utf8 ou latin1. Cette page explique ce que la fonction retourne, sa syntaxe dans les deux styles, quand y recourir et les pièges d'encodage qu'elle vous aide à détecter.

Ce que le jeu de caractères contrôle

Le jeu de caractères de la connexion indique à MySQL comment interpréter les octets que vous envoyez (dans les instructions INSERT/UPDATE et les paramètres de requête) et comment encoder les octets qu'il renvoie. Si le jeu de caractères de la connexion ne correspond pas à l'encodage réel de vos chaînes, vous obtenez du mojibake — des lettres accentuées corrompues, des emoji qui deviennent ???? et une perte de données silencieuse.

mysqli_character_set_name() est le moyen le plus rapide d'inspecter ce paramètre à l'exécution. C'est un diagnostic en lecture seule : il ne modifie rien. Pour changer le jeu de caractères, utilisez set_charset().

Syntaxe

La fonction existe sous forme orientée objet et sous forme procédurale. Elles sont équivalentes — choisissez celle qui correspond à votre base de code.

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

// Procedural style
string mysqli_character_set_name(mysqli $mysqli)

• Paramètre (forme procédurale uniquement) : $mysqli — une connexion retournée par mysqli_connect() ou new mysqli().
• Valeur de retour : une chaîne contenant le nom du jeu de caractères actuel (ex. "utf8mb4"). Elle ne retourne pas false ; sur une connexion valide, il y a toujours un jeu de caractères.

Comment utiliser mysqli_character_set_name()

Appelez-la sur une connexion ouverte et affichez le résultat :

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

Une sortie typique, avant tout réglage explicite, correspond au défaut du serveur :

Character set: utf8mb4

La même chose en style procédural :

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

Lire le jeu de caractères après l'avoir modifié

Comme la fonction reporte le paramètre en temps réel, elle est pratique pour confirmer qu'un appel à set_charset() a bien pris effet :

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

Pourquoi définir le jeu de caractères plutôt que simplement le lire

mysqli_character_set_name() ne fait que rapporter le jeu de caractères — il ne peut pas le corriger. Pour une prise en charge complète d'Unicode (y compris les emoji et de nombreux caractères CJK), définissez utf8mb4 juste après la connexion :

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

Remarques et pièges :

• Préférez utf8mb4 à utf8. Le utf8 natif de MySQL est un alias sur 3 octets qui ne peut pas stocker des caractères sur 4 octets tels que les emoji. utf8mb4 est le vrai UTF-8 complet.
• N'exécutez pas SET NAMES ... comme requête pour changer le jeu de caractères. Cela met à jour la session côté serveur mais laisse la bibliothèque cliente dans l'ignorance, ce qui casse real_escape_string(). Utilisez toujours set_charset() pour que les deux restent synchronisés.
• Le nom retourné est le jeu de caractères de la connexion, indépendant du jeu de caractères d'une colonne ou d'une table défini dans le schéma.

Fonctions associées

• mysqli_set_charset() — modifier le jeu de caractères de la connexion.
• mysqli_get_charset() — obtenir un objet complet décrivant le jeu de caractères (interclassement, longueur en octets, etc.).
• mysqli_connect_errno() / mysqli_connect_error() — détecter les échecs de connexion avant de lire le jeu de caractères.
• Vue d'ensemble de PHP MySQLi — l'extension MySQLi dans son ensemble.

Conclusion

mysqli_character_set_name() est un diagnostic simple et fiable pour vérifier quel jeu de caractères utilise une connexion MySQL. Lisez-le pour déboguer les problèmes d'encodage, puis corrigez-les avec set_charset("utf8mb4") afin que votre application stocke correctement les textes accentués et les emoji.

Pratique