utf8_decode()

La funzione utf8_decode() è una funzione PHP integrata che converte una stringa dalla codifica UTF-8 a ISO-8859-1 (chiamata anche Latin-1). UTF-8 può rappresentare ogni carattere Unicode, mentre ISO-8859-1 è una codifica a singolo byte che copre solo i primi 256 code point Unicode (lettere dell'Europa occidentale, cifre e punteggiatura).

Questa pagina spiega cosa fa utf8_decode(), quando è effettivamente necessaria, il suo sostituto moderno e come si comporta con i caratteri che esulano da ISO-8859-1.

Quando (e se) utilizzarla

Hai bisogno di utf8_decode() solo quando stai passando testo UTF-8 a un sistema più vecchio che comprende esclusivamente ISO-8859-1 — ad esempio una colonna di database legacy, un report a larghezza fissa o un'API di terze parti che precede Unicode. Per qualsiasi cosa nuova, mantieni i dati in UTF-8 dall'inizio alla fine e non avrai mai bisogno di questa funzione.

Attenzione

utf8_decode() è deprecata a partire da PHP 8.2 e verrà rimossa in una versione futura. Sostituiscila con mb_convert_encoding($string, 'ISO-8859-1', 'UTF-8') (l'estensione mbstring) o iconv('UTF-8', 'ISO-8859-1', $string). La conversione inversa è effettuata da utf8_encode().

Una limitazione fondamentale: ISO-8859-1 non ha posizioni per caratteri come €, ™, emoji o qualsiasi script non latino. Quando utf8_decode() incontra un carattere che non può rappresentare, lo sostituisce con un punto interrogativo (?) — il carattere originale viene perso. Ecco perché la funzione è con perdita e perché rimanere in UTF-8 è quasi sempre la scelta migliore.

Sintassi

La sintassi della funzione utf8_decode() è la seguente:

utf8_decode(string $string): string

Parametro	Descrizione
`$string`	La stringa con codifica UTF-8 da convertire in ISO-8859-1.

Valore restituito: la stringa ISO-8859-1 convertita. I byte che non sono UTF-8 valido e i caratteri privi di equivalente in ISO-8859-1 vengono sostituiti con un punto interrogativo (?).

Esempi di utilizzo

Vediamo alcuni esempi pratici di utilizzo di utf8_decode() in PHP.

Esempio 1: Conversione di testo con codifica UTF-8 in ISO-8859-1

La stringa "Zoë" è memorizzata nello script come UTF-8, dove la ë occupa due byte (c3 ab). Dopo la decodifica, ë diventa il singolo byte ISO-8859-1 eb. Stampiamo i byte grezzi con bin2hex() per rendere visibile la modifica a livello di byte:

Conversione di testo con codifica UTF-8 in ISO-8859-1 in PHP

php— editable, runs on the server

L'output è:

5a6feb

I quattro byte UTF-8 (Z, o e la ë a due byte) si riducono a tre byte ISO-8859-1: 5a (Z), 6f (o) e eb (ë). La stringa è ora di un byte più corta perché il carattere accentato è codificato in un singolo byte anziché in due.

Esempio 2: Caratteri che non possono essere rappresentati

Poiché ISO-8859-1 dispone solo di 256 code point, qualsiasi carattere al di fuori di tale intervallo viene perso. Il simbolo dell'euro (€) è un esempio classico — non esiste in Latin-1:

<?php

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

?>

Il carattere € viene sostituito con ?. Se hai bisogno di preservare caratteri come questo, non convertire in ISO-8859-1 — mantieni il testo in UTF-8 o utilizza una codifica di destinazione più ricca.

Esempio 3: Lettura di testo UTF-8 da XML

SimpleXML analizza sempre XML come UTF-8. Se devi passare quel testo a un sistema Latin-1, decodifica ogni valore mentre lo leggi con simplexml_load_file():

Conversione di testo con codifica UTF-8 da XML in 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";
}

?>

Questo carica data.xml, itera su ogni elemento <item> e decodifica il testo di <title> e <description> da UTF-8 a ISO-8859-1. Convertire ogni nodo in (string) trasforma prima lo SimpleXMLElement in una stringa semplice prima della decodifica.

Affinché questo esempio funzioni, data.xml deve contenere una struttura come questa:

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

Conclusione

utf8_decode() converte il testo UTF-8 in ISO-8859-1, eliminando qualsiasi carattere che Latin-1 non può rappresentare. È utile per comunicare con sistemi legacy, ma è deprecata in PHP 8.2+ e con perdita, quindi preferisci mb_convert_encoding() o iconv() e mantieni i dati in UTF-8 ogni volta che puoi.

Per effettuare la conversione nella direzione opposta, consulta utf8_encode(). Per ulteriori informazioni sull'utilizzo del testo in PHP, consulta il riferimento alle funzioni stringa PHP.

Esercizio

Pratica

Cosa fa la funzione utf8_decode in PHP?

Codifica una stringa UTF-8 in ISO-8859-1.Decodifica una stringa UTF-8 in ISO-8859-1.Decodifica una stringa UTF-8 in ASCII.Codifica una stringa ISO-8859-1 in UTF-8.