Guide complet sur la fonction mysqli_set_charset en PHP

Lorsque vous stockez des noms, des commentaires ou des emoji dans MySQL, les octets ne font l'aller-retour correctement que si PHP et la base de données s'accordent sur un jeu de caractères — la correspondance entre les octets et les caractères. La fonction mysqli_set_charset définit le jeu de caractères pour la connexion entre votre script PHP et le serveur MySQL, afin que tout ce que vous envoyez et recevez soit interprété de la même façon des deux côtés.

Cette page explique ce que fait la fonction, pourquoi définir le jeu de caractères sur la connexion est important (et pourquoi c'est aussi une mesure de sécurité), et comment l'utiliser avec les API mysqli procédurale et orientée objet.

Ce que fait mysqli_set_charset

mysqli_set_charset indique au serveur MySQL quel jeu de caractères le client (votre script PHP) utilisera pour le reste de la connexion. Cela affecte la façon dont les chaînes de requête sont interprétées, comment les résultats sont encodés au retour, et quels octets mysqli_real_escape_string() traite comme spéciaux.

La signature procédurale prend d'abord la connexion, puis le nom du jeu de caractères, et renvoie true en cas de succès ou false en cas d'échec :

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

La forme orientée objet est une méthode sur l'objet de connexion :

$connection->set_charset($charset);

L'argument $charset est un nom de jeu de caractères MySQL tel que utf8mb4, utf8 ou latin1 — pas un nom d'encodage PHP. Utilisez utf8mb4 pour une prise en charge complète d'Unicode, y compris les caractères sur 4 octets comme les emoji ; l'alias utf8 plus ancien dans MySQL ne stocke que jusqu'à 3 octets par caractère et ne peut pas contenir d'emoji.

Définissez-le sur la connexion, pas seulement dans les requêtes. Exécuter SET NAMES utf8mb4 comme requête change le jeu de caractères côté serveur, mais ne met pas à jour la valeur utilisée par la bibliothèque cliente C pour l'échappement. mysqli_set_charset met à jour les deux, ce qui en fait la méthode correcte et sûre pour changer de jeu de caractères.

Connexion et définition du jeu de caractères

mysqli_set_charset nécessite une connexion existante, donc ouvrez-en une d'abord avec mysqli_connect. L'exemple ci-dessous se connecte, puis définit immédiatement 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

Après le succès de l'appel, mysqli_character_set_name indique le jeu de caractères actif, confirmant que le changement a pris effet.

Exemple orienté objet

Si vous utilisez l'API mysqli orientée objet, appelez set_charset() comme méthode. Il est recommandé de le faire juste après la construction de la connexion, avant d'exécuter toute requête :

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

Gestion des échecs

mysqli_set_charset renvoie false si le serveur ne prend pas en charge le jeu de caractères demandé (par exemple, une faute de frappe comme utf8mb44). Vérifiez toujours la valeur de retour plutôt que de supposer le succès :

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

Vous pouvez appeler la fonction plusieurs fois sur la même connexion pour changer de jeu de caractères en cours de session, mais en pratique vous le définissez une fois juste après la connexion et le laissez en place.

Pourquoi c'est important

• Texte correct. Sans jeu de caractères correspondant, les lettres accentuées et les scripts non latins reviennent sous forme de ? ou de mojibake (caractères illisibles comme é au lieu de é).
• Emoji et Unicode complet. Seul utf8mb4 stocke les caractères sur 4 octets ; utf8 les supprime ou les tronque silencieusement.
• Sécurité. mysqli_real_escape_string() effectue l'échappement en fonction du jeu de caractères de la connexion. Le définir correctement ferme une catégorie de vecteurs d'injection SQL qui exploitent les incohérences multioctets. Même ainsi, privilégiez les requêtes préparées à l'échappement manuel.

Fonctions associées

• mysqli_connect — ouvre la connexion que vous passez à set_charset.
• mysqli_get_charset — obtient un objet complet décrivant le jeu de caractères actuel (collation, commentaire, numéro).
• mysqli_character_set_name — obtient uniquement le nom du jeu de caractères actif.
• mysqli_select_db — change la base de données active sur une connexion existante.

Conclusion

mysqli_set_charset aligne le jeu de caractères de votre script PHP avec votre connexion MySQL, garantissant que le texte fait l'aller-retour correctement et que l'échappement se comporte de manière sûre. Définissez-le sur utf8mb4 juste après la connexion, vérifiez sa valeur de retour, et vous avez couvert les cas courants — des noms accentués aux emoji.

Pratique