utf8_encode()

A função utf8_encode() é uma função nativa do PHP que converte uma string de ISO-8859-1 (Latin-1) para UTF-8. É útil quando você recebe texto Latin-1 — de um banco de dados legado, um arquivo ou uma API antiga — e precisa exibi-lo corretamente em um sistema que espera UTF-8.

Esta página explica o que a função faz, como ela funciona no nível de bytes, quando (e quando não) usá-la, e as alternativas modernas que você deve preferir nas versões atuais do PHP.

Descontinuada e removida. utf8_encode() foi descontinuada no PHP 8.2 e removida no PHP 8.3. O novo código deve usar mb_convert_encoding() ou iconv() — veja Alternativas modernas abaixo. Esta página documenta a função legada para as muitas bases de código que ainda dependem dela.

O que significa "codificação" aqui

Uma codificação de caracteres é um mapeamento entre caracteres e os bytes que os representam. ISO-8859-1 é uma codificação de um único byte: cada caractere é exatamente um byte (256 valores possíveis), o que cobre letras do oeste europeu como é, ñ e ü. UTF-8 é uma codificação de largura variável onde esses mesmos caracteres acentuados ocupam dois bytes.

utf8_encode() realiza uma tarefa específica: lê cada byte da entrada como um ponto de código ISO-8859-1 e o reescreve como a sequência de bytes UTF-8 equivalente. Ela não detecta a codificação da entrada — sempre assume que a entrada é ISO-8859-1. Se você passar uma string que já está em UTF-8, obterá uma saída corrompida ("mojibake" com dupla codificação).

Sintaxe

utf8_encode(string $string): string

Valor de retorno: o mesmo texto recodificado em UTF-8.

Exemplos de uso

Veja alguns exemplos práticos do uso de utf8_encode() em PHP.

Exemplo 1: Convertendo texto ISO-8859-1 para UTF-8

Suponha que você tenha uma string com codificação ISO-8859-1 que deseja converter para UTF-8. Você pode usar utf8_encode() para isso:

Este código define uma variável string $text contendo texto ISO-8859-1, converte-o para UTF-8 com utf8_encode() e imprime o resultado. Observe a ressalva no comentário: a string de origem deve realmente ser ISO-8859-1. Se o seu editor salvar o arquivo como UTF-8, o é já será dois bytes e utf8_encode() irá corrompê-lo para é.

Exemplo 2: Visualizando a mudança no nível de bytes

Para tornar a conversão concreta, inspecione o tamanho em bytes antes e depois. O caractere acentuado cresce de um byte para dois:

<?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() conta bytes, não caracteres, portanto a mesma letra reporta comprimento 1 em Latin-1 e 2 em UTF-8. Essa expansão de um para dois bytes é exatamente o que faz o texto convertido ser renderizado corretamente em um contexto UTF-8.

Exemplo 3: Convertendo texto ISO-8859-1 de um arquivo XML

Suponha que você tenha um arquivo XML declarado como ISO-8859-1 que deseja ler e converter para UTF-8. Você pode usar a biblioteca SimpleXML para ler o arquivo e utf8_encode() para converter cada valor:

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

Isso carrega um arquivo XML declarado como ISO-8859-1 com simplexml_load_file(), itera sobre cada elemento <item> e converte o texto de <title> e <description> para UTF-8 antes de imprimir. (Os valores de SimpleXMLElement são convertidos para string por utf8_encode().)

Quando usar (e quando não usar)

Use utf8_encode() somente quando todos estes critérios forem verdadeiros:

• A entrada é genuinamente ISO-8859-1 / Latin-1 (não Windows-1252, não já em UTF-8).
• Você está no PHP 8.2 ou anterior, onde a função ainda existe.
• Você quer uma conversão Latin-1 → UTF-8 rápida e sem dependências.

Evite-a quando:

• A origem pode ser Windows-1252 (comum para texto do Windows / Excel). O Windows-1252 reutiliza o intervalo 0x80–0x9F para caracteres como € e aspas tipográficas que o ISO-8859-1 deixa indefinidos — eles serão perdidos ou incorretos. Use mb_convert_encoding($s, 'UTF-8', 'Windows-1252') em vez disso.
• Você não sabe a codificação real da entrada. Detecte ou declare-a explicitamente em vez de adivinhar.
• Você usa PHP 8.3+, onde a função foi completamente removida.

Alternativas modernas

Como utf8_encode() foi removida no PHP 8.3, prefira as funções de string multibyte ou iconv, que permitem nomear a codificação de origem explicitamente:

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

Ambas produzem os mesmos dois bytes (0xC3 0xA9) que utf8_encode(), mas tornam a codificação de origem parte da chamada — portanto, também funcionam para Windows-1252, ISO-8859-15 e dezenas de outras codificações.

Funções relacionadas

• utf8_decode() — o inverso: converte UTF-8 de volta para ISO-8859-1.
• json_encode() — produz saída UTF-8 e escapa caracteres multibyte.
• PHP Strings — visão geral do trabalho com texto em PHP.

Conclusão

utf8_encode() converte texto ISO-8859-1 (Latin-1) para UTF-8 recodificando cada byte — transformando caracteres acentuados de um byte na sua forma UTF-8 de dois bytes. É conveniente, mas não detecta a codificação real da entrada, e foi descontinuada no PHP 8.2 e removida no PHP 8.3. Para qualquer novo código, use mb_convert_encoding() ou iconv(), que permitem especificar a codificação de origem explicitamente e lidam com uma gama muito mais ampla de conjuntos de caracteres.

Prática