utf8_decode()

A função utf8_decode() é uma função nativa do PHP que converte uma string de codificação UTF-8 para ISO-8859-1 (também chamada de Latin-1). O UTF-8 pode representar todos os caracteres Unicode, enquanto o ISO-8859-1 é uma codificação de byte único que cobre apenas os primeiros 256 pontos de código Unicode (letras ocidentais, dígitos e pontuação).

Esta página explica o que utf8_decode() faz, quando você realmente precisa dela, a substituição moderna e como ela se comporta com caracteres que ficam fora do ISO-8859-1.

Quando (e se) usá-la

Você só precisa de utf8_decode() quando estiver alimentando texto UTF-8 em um sistema mais antigo que só entende ISO-8859-1 — por exemplo, uma coluna de banco de dados legado, um relatório de largura fixa ou uma API de terceiros anterior ao Unicode. Para qualquer coisa nova, mantenha seus dados em UTF-8 de ponta a ponta e você nunca precisará dessa função.

Uma limitação importante: o ISO-8859-1 não possui espaço para caracteres como €, ™, emoji ou qualquer script não latino. Quando utf8_decode() encontra um caractere que não pode representar, ele o substitui por um ponto de interrogação (?) — o caractere original é perdido. É por isso que a função é destrutiva e por que manter o UTF-8 quase sempre é a melhor escolha.

Sintaxe

A sintaxe da função utf8_decode() é a seguinte:

utf8_decode(string $string): string

Valor de retorno: a string ISO-8859-1 convertida. Bytes que não são UTF-8 válido e caracteres sem equivalente ISO-8859-1 são convertidos em um ponto de interrogação (?).

Exemplos de Uso

Vejamos alguns exemplos práticos de uso de utf8_decode() em PHP.

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

A string "Zoë" é armazenada no seu script como UTF-8, onde o ë ocupa dois bytes (c3 ab). Após a decodificação, ë torna-se o byte ISO-8859-1 único eb. Imprimimos os bytes brutos com bin2hex() para que a alteração no nível de byte seja visível:

Convertendo texto codificado em UTF-8 para ISO-8859-1 em PHP

A saída é:

5a6feb

Os quatro bytes UTF-8 (Z, o e o ë de dois bytes) colapsam para três bytes ISO-8859-1: 5a (Z), 6f (o) e eb (ë). A string agora é um byte mais curta porque o caractere acentuado é codificado em um único byte em vez de dois.

Exemplo 2: Caracteres que não podem ser representados

Como o ISO-8859-1 tem apenas 256 pontos de código, qualquer caractere fora desse intervalo é perdido. O símbolo do euro (€) é um exemplo clássico — ele não existe no Latin-1:

<?php

echo utf8_decode("Price: €5");  // Price: ?5

?>

O € é substituído por ?. Se você precisar preservar caracteres como este, não converta para ISO-8859-1 — mantenha o texto em UTF-8 ou use uma codificação de destino mais rica.

Exemplo 3: Lendo texto UTF-8 de XML

O SimpleXML sempre analisa XML como UTF-8. Se você precisar passar esse texto para um sistema Latin-1, decodifique cada valor ao lê-lo com simplexml_load_file():

Convertendo texto codificado em UTF-8 de XML em PHP

<?php

$xml = simplexml_load_file("data.xml");
foreach ($xml->item as $item) {
    $title = utf8_decode((string) $item->title);
    $description = utf8_decode((string) $item->description);
    echo "$title: $description\n";
}

?>

Isso carrega data.xml, percorre cada elemento <item> e decodifica o texto de <title> e <description> de UTF-8 para ISO-8859-1. Converter cada nó para (string) primeiro transforma o SimpleXMLElement em uma string simples antes da decodificação.

Para que este exemplo funcione, data.xml deve conter uma estrutura como esta:

<root>
  <item>
    <title>Example Title</title>
    <description>Example Description</description>
  </item>
</root>

Conclusão

utf8_decode() converte texto UTF-8 para ISO-8859-1, descartando qualquer caractere que o Latin-1 não consiga representar. É útil para comunicação com sistemas legados, mas está obsoleta no PHP 8.2+ e é destrutiva, portanto prefira mb_convert_encoding() ou iconv() e mantenha seus dados em UTF-8 sempre que possível.

Para fazer a conversão inversa, consulte utf8_encode(). Para saber mais sobre como trabalhar com texto em PHP, consulte a referência de funções de string PHP.

Prática