utf8_encode()

La fonction utf8_encode() est une fonction intégrée PHP qui convertit une chaîne de l'encodage ISO-8859-1 (Latin-1) vers UTF-8. Elle est utile lorsque vous recevez du texte Latin-1 — provenant d'une ancienne base de données, d'un fichier ou d'une vieille API — et que vous avez besoin de l'afficher correctement dans un système qui attend de l'UTF-8.

Cette page explique ce que fait la fonction, comment elle fonctionne au niveau des octets, quand l'utiliser (et quand ne pas l'utiliser), ainsi que les remplacements modernes à privilégier dans les versions actuelles de PHP.

Dépréciée, puis supprimée. utf8_encode() a été dépréciée en PHP 8.2 et supprimée en PHP 8.3. Le nouveau code devrait utiliser mb_convert_encoding() ou iconv() à la place — voir Remplacements modernes ci-dessous. Cette page documente la fonction héritée pour les nombreuses bases de code qui en dépendent encore.

Ce que signifie « encodage » ici

Un encodage de caractères est une correspondance entre des caractères et les octets qui les représentent. ISO-8859-1 est un encodage sur un seul octet : chaque caractère correspond exactement à un octet (256 valeurs possibles), ce qui couvre les lettres d'Europe occidentale telles que é, ñ et ü. UTF-8 est un encodage à largeur variable où ces mêmes caractères accentués occupent deux octets.

utf8_encode() accomplit une tâche spécifique : elle lit chaque octet de l'entrée comme un point de code ISO-8859-1 et le réécrit sous la forme de la séquence d'octets UTF-8 équivalente. Elle ne détecte pas l'encodage de l'entrée — elle suppose toujours que l'entrée est en ISO-8859-1. Si vous lui fournissez une chaîne déjà en UTF-8, vous obtiendrez un résultat « mojibake » corrompu (double encodage).

Syntaxe

utf8_encode(string $string): string

Valeur de retour : le même texte ré-encodé en UTF-8.

Exemples d'utilisation

Voyons quelques exemples pratiques d'utilisation de utf8_encode() en PHP.

Exemple 1 : Convertir du texte ISO-8859-1 en UTF-8

Supposons que vous ayez une chaîne en encodage ISO-8859-1 que vous souhaitez convertir en UTF-8. Vous pouvez utiliser utf8_encode() pour cela :

Ce code définit une variable string $text contenant du texte ISO-8859-1, le convertit en UTF-8 avec utf8_encode(), et affiche le résultat. Notez la mise en garde dans le commentaire : la chaîne source doit réellement être en ISO-8859-1. Si votre éditeur enregistre le fichier en UTF-8, le é occupe déjà deux octets et utf8_encode() le transformera en é.

Exemple 2 : Observer le changement au niveau des octets

Pour rendre la conversion concrète, inspectez la longueur en octets avant et après. Le caractère accentué passe d'un octet à deux :

<?php
$latin1 = "\xE9";            // a single byte: 'é' in ISO-8859-1
echo strlen($latin1);        // 1
$utf8 = utf8_encode($latin1);
echo strlen($utf8);          // 2  -> the bytes 0xC3 0xA9
echo bin2hex($utf8);         // c3a9
?>

strlen() compte les octets, pas les caractères, donc la même lettre renvoie une longueur de 1 en Latin-1 et de 2 en UTF-8. Cette expansion d'un octet à deux est exactement ce qui permet au texte converti de s'afficher correctement dans un contexte UTF-8.

Exemple 3 : Convertir du texte XML encodé en ISO-8859-1

Supposons que vous ayez un fichier XML déclaré en ISO-8859-1 que vous souhaitez lire et convertir en UTF-8. Vous pouvez utiliser la bibliothèque SimpleXML pour lire le fichier et utf8_encode() pour convertir chaque valeur :

<?php
$xml = simplexml_load_file("data.xml");
foreach ($xml->item as $item) {
  $title = utf8_encode($item->title);
  $description = utf8_encode($item->description);
  echo "$title: $description\n";
}
?>

Ce code charge un fichier XML déclaré en ISO-8859-1 avec simplexml_load_file(), itère sur chaque élément <item>, et convertit le texte des balises <title> et <description> en UTF-8 avant de l'afficher. (Les valeurs SimpleXMLElement sont converties en chaînes par utf8_encode().)

Quand l'utiliser (et quand ne pas l'utiliser)

Utilisez utf8_encode() uniquement lorsque toutes ces conditions sont remplies :

• L'entrée est genuinement en ISO-8859-1 / Latin-1 (pas en Windows-1252, pas déjà en UTF-8).
• Vous utilisez PHP 8.2 ou antérieur, où la fonction existe encore.
• Vous souhaitez une conversion Latin-1 → UTF-8 rapide, sans dépendance.

Évitez-la lorsque :

• La source pourrait être en Windows-1252 (courant pour les textes issus de Windows / Excel). Windows-1252 réutilise la plage 0x80–0x9F pour des caractères comme € et les guillemets courbes que ISO-8859-1 laisse indéfinis — ceux-ci seront perdus ou erronés. Utilisez plutôt mb_convert_encoding($s, 'UTF-8', 'Windows-1252').
• Vous ne connaissez pas réellement l'encodage de l'entrée. Détectez-le ou déclarez-le explicitement plutôt que de deviner.
• Vous ciblez PHP 8.3+, où la fonction a été entièrement supprimée.

Remplacements modernes

Puisque utf8_encode() est supprimée en PHP 8.3, préférez les fonctions de la bibliothèque multibyte-string ou iconv, qui vous permettent de nommer explicitement l'encodage source :

<?php
$latin1 = "\xE9"; // 'é' in ISO-8859-1

// mbstring extension (recommended)
$utf8 = mb_convert_encoding($latin1, 'UTF-8', 'ISO-8859-1');

// iconv extension
$utf8 = iconv('ISO-8859-1', 'UTF-8', $latin1);

echo bin2hex($utf8); // c3a9 in both cases
?>

Les deux produisent les mêmes deux octets (0xC3 0xA9) que utf8_encode(), mais ils font de l'encodage source une partie de l'appel — ils fonctionnent donc aussi pour Windows-1252, ISO-8859-15 et des dizaines d'autres encodages.

Fonctions associées

• utf8_decode() — l'inverse : convertit l'UTF-8 en ISO-8859-1.
• json_encode() — produit une sortie UTF-8 et échappe les caractères multioctets.
• PHP Strings — aperçu du travail avec le texte en PHP.

Conclusion

utf8_encode() convertit le texte ISO-8859-1 (Latin-1) en UTF-8 en ré-encodant chaque octet — transformant les caractères accentués sur un seul octet en leur forme UTF-8 sur deux octets. Elle est pratique mais aveugle à l'encodage réel de l'entrée, et elle est dépréciée en PHP 8.2 et supprimée en PHP 8.3. Pour tout nouveau code, utilisez mb_convert_encoding() ou iconv(), qui vous permettent de spécifier l'encodage source explicitement et de gérer une gamme bien plus large de jeux de caractères.

Practice