(PHP 4, PHP 5, PHP 7, PHP 8)
utf8_encode — Converte uma string ISO-8859-1 em UTF-8
Esta função foi DESCONTINUADA a partir do PHP 8.2.0. O uso desta função é fortemente desencorajado.
Esta função converte a string string da codificação
ISO-8859-1 para a UTF-8.
Nota:
Esta função não tenta descobrir a codificação da string fornecida, ela assume que esteja codificada como ISO-8859-1 (também conhecida como "Latin 1") e converte-a para UTF-8. Como toda sequência de bytes é uma string ISO-8859-1 válida, isto nunca irá resultar em erro, mas não irá resultar em uma string útil se uma codificação diferente era a intenção.
Muitas páginas da web que dizem usar a codificação
ISO-8859-1na verdade usam a codificação similarWindows-1252, e os navegadores irão interpretar as páginasISO-8859-1comoWindows-1252.Windows-1252apresenta caracteres imprimíveis adicionais, como o símbolo do Euro (€) e aspas inglesas (“”), ao invés de certos caracteres de controleISO-8859-1. Esta função não converterá esses caracteresWindows-1252corretamente. Use uma função diferente se a conversão deWindows-1252for requerida.
stringUma string em ISO-8859-1.
Retorna a conversão em UTF-8 da string.
| Versão | Descrição |
|---|---|
| 8.2.0 | Esta função foi descontinuada. |
| 7.2.0 | Esta função foi movida de extensão XML para o núcleo do PHP. Em versões anteriores, estava disponível somente se a extensão XML estivesse instalada. |
Exemplo #1 Exemplo básico
<?php
// Converte a string 'Zoë' de ISO 8859-1 para UTF-8
$iso8859_1_string = "\x5A\x6F\xEB";
$utf8_string = utf8_encode($iso8859_1_string);
echo bin2hex($utf8_string), "\n";
?>O exemplo acima produzirá:
5a6fc3ab
Nota: Descontinuação e alternativas
Esta função foi descontinuada a partir do PHP 8.2.0, e será removida em uma versão futura. Usos existentes devem ser verificados e substituídos com alternativas apropriadas.
Funcionalidade similar pode ser obtida com mb_convert_encoding(), que suporta ISO-8859-1 e muitas outras codificações de caracteres.
<?php
$iso8859_1_string = "\xEB"; // 'ë' (e com trema) em ISO-8859-1
$utf8_string = mb_convert_encoding($iso8859_1_string, 'UTF-8', 'ISO-8859-1');
echo bin2hex($utf8_string), "\n";
$iso8859_7_string = "\xEB"; // a mesma string em ISO-8859-7 representa 'λ' (letra grega lambda minúscula)
$utf8_string = mb_convert_encoding($iso8859_7_string, 'UTF-8', 'ISO-8859-7');
echo bin2hex($utf8_string), "\n";
$windows_1252_string = "\x80"; // '€' (símbolo do Euro) em Windows-1252, mas não em ISO-8859-1
$utf8_string = mb_convert_encoding($windows_1252_string, 'UTF-8', 'Windows-1252');
echo bin2hex($utf8_string), "\n";
?>O exemplo acima produzirá:
c3ab cebb e282acOutros exemplos que podem estar disponíveis dependendo das extensões instaladas são UConverter::transcode() e iconv().
Todos os exemplos a seguir dão o mesmo resultado:
<?php
$iso8859_1_string = "\x5A\x6F\xEB"; // 'Zoë' em ISO-8859-1
$utf8_string = utf8_encode($iso8859_1_string);
echo bin2hex($utf8_string), "\n";
$utf8_string = mb_convert_encoding($iso8859_1_string, 'UTF-8', 'ISO-8859-1');
echo bin2hex($utf8_string), "\n";
$utf8_string = UConverter::transcode($iso8859_1_string, 'UTF8', 'ISO-8859-1');
echo bin2hex($utf8_string), "\n";
$utf8_string = iconv('ISO-8859-1', 'UTF-8', $iso8859_1_string);
echo bin2hex($utf8_string), "\n";
?>O exemplo acima produzirá:
5a6fc3ab 5a6fc3ab 5a6fc3ab 5a6fc3ab
Please note that utf8_encode only converts a string encoded in ISO-8859-1 to UTF-8. A more appropriate name for it would be "iso88591_to_utf8". If your text is not encoded in ISO-8859-1, you do not need this function. If your text is already in UTF-8, you do not need this function. In fact, applying this function to text that is not encoded in ISO-8859-1 will most likely simply garble that text.
If you need to convert text from any encoding to any other encoding, look at iconv() instead.Here's some code that addresses the issue that Steven describes in the previous comment;
<?php
/* This structure encodes the difference between ISO-8859-1 and Windows-1252,
as a map from the UTF-8 encoding of some ISO-8859-1 control characters to
the UTF-8 encoding of the non-control characters that Windows-1252 places
at the equivalent code points. */
$cp1252_map = array(
"\xc2\x80" => "\xe2\x82\xac", /* EURO SIGN */
"\xc2\x82" => "\xe2\x80\x9a", /* SINGLE LOW-9 QUOTATION MARK */
"\xc2\x83" => "\xc6\x92", /* LATIN SMALL LETTER F WITH HOOK */
"\xc2\x84" => "\xe2\x80\x9e", /* DOUBLE LOW-9 QUOTATION MARK */
"\xc2\x85" => "\xe2\x80\xa6", /* HORIZONTAL ELLIPSIS */
"\xc2\x86" => "\xe2\x80\xa0", /* DAGGER */
"\xc2\x87" => "\xe2\x80\xa1", /* DOUBLE DAGGER */
"\xc2\x88" => "\xcb\x86", /* MODIFIER LETTER CIRCUMFLEX ACCENT */
"\xc2\x89" => "\xe2\x80\xb0", /* PER MILLE SIGN */
"\xc2\x8a" => "\xc5\xa0", /* LATIN CAPITAL LETTER S WITH CARON */
"\xc2\x8b" => "\xe2\x80\xb9", /* SINGLE LEFT-POINTING ANGLE QUOTATION */
"\xc2\x8c" => "\xc5\x92", /* LATIN CAPITAL LIGATURE OE */
"\xc2\x8e" => "\xc5\xbd", /* LATIN CAPITAL LETTER Z WITH CARON */
"\xc2\x91" => "\xe2\x80\x98", /* LEFT SINGLE QUOTATION MARK */
"\xc2\x92" => "\xe2\x80\x99", /* RIGHT SINGLE QUOTATION MARK */
"\xc2\x93" => "\xe2\x80\x9c", /* LEFT DOUBLE QUOTATION MARK */
"\xc2\x94" => "\xe2\x80\x9d", /* RIGHT DOUBLE QUOTATION MARK */
"\xc2\x95" => "\xe2\x80\xa2", /* BULLET */
"\xc2\x96" => "\xe2\x80\x93", /* EN DASH */
"\xc2\x97" => "\xe2\x80\x94", /* EM DASH */
"\xc2\x98" => "\xcb\x9c", /* SMALL TILDE */
"\xc2\x99" => "\xe2\x84\xa2", /* TRADE MARK SIGN */
"\xc2\x9a" => "\xc5\xa1", /* LATIN SMALL LETTER S WITH CARON */
"\xc2\x9b" => "\xe2\x80\xba", /* SINGLE RIGHT-POINTING ANGLE QUOTATION*/
"\xc2\x9c" => "\xc5\x93", /* LATIN SMALL LIGATURE OE */
"\xc2\x9e" => "\xc5\xbe", /* LATIN SMALL LETTER Z WITH CARON */
"\xc2\x9f" => "\xc5\xb8" /* LATIN CAPITAL LETTER Y WITH DIAERESIS*/
);
function cp1252_to_utf8($str) {
global $cp1252_map;
return strtr(utf8_encode($str), $cp1252_map);
}
?>If you haven't guessed already: If the UTF-8 character has no representation in the ISO-8859-1 codepage, a ? will be returned. You might want to wrap a function around this to make sure you aren't saving a bunch of ???? into your database.