utf8_encode()

La funzione utf8_encode() è una funzione built-in di PHP che converte una stringa da codifica ISO-8859-1 (Latin-1) a UTF-8. È utile quando si riceve testo Latin-1 — da un database legacy, un file o una vecchia API — e si ha bisogno che venga visualizzato correttamente in un sistema che si aspetta UTF-8.

Questa pagina spiega cosa fa la funzione, come funziona a livello di byte, quando usarla (e quando no) e le alternative moderne da preferire nelle versioni correnti di PHP.

Deprecata, poi rimossa. utf8_encode() è stata deprecata in PHP 8.2 e rimossa in PHP 8.3. Il nuovo codice dovrebbe usare mb_convert_encoding() oppure iconv() — vedi Alternative moderne più avanti. Questa pagina documenta la funzione legacy per i numerosi codebase che vi fanno ancora affidamento.

Cosa significa "codifica" in questo contesto

Una codifica dei caratteri è una mappatura tra i caratteri e i byte che li rappresentano. ISO-8859-1 è una codifica a byte singolo: ogni carattere è esattamente un byte (256 valori possibili), che copre le lettere dell'Europa occidentale come é, ñ e ü. UTF-8 è una codifica a larghezza variabile in cui quegli stessi caratteri accentati occupano due byte.

utf8_encode() svolge un compito specifico: legge ogni byte dell'input come un code point ISO-8859-1 e lo riscrive come sequenza di byte UTF-8 equivalente. Non rileva la codifica dell'input — assume sempre che l'input sia ISO-8859-1. Se si fornisce una stringa già in UTF-8, si ottiene un output "mojibake" (doppia codifica) corrotto.

Sintassi

utf8_encode(string $string): string

Valore restituito: lo stesso testo ri-codificato in UTF-8.

Esempi d'uso

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

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

Supponiamo di avere una stringa con codifica ISO-8859-1 che si vuole convertire in UTF-8. È possibile usare utf8_encode() per farlo:

Questo codice definisce una variabile stringa $text contenente testo ISO-8859-1, la converte in UTF-8 con utf8_encode() e stampa il risultato. Si noti l'avvertenza nel commento: la stringa sorgente deve essere effettivamente in ISO-8859-1. Se l'editor salva il file in UTF-8, la é è già due byte e utf8_encode() la trasformerà in é.

Esempio 2: Vedere il cambiamento a livello di byte

Per rendere concreta la conversione, si può ispezionare la lunghezza in byte prima e dopo. Il carattere accentato passa da un byte a due:

<?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 i byte, non i caratteri, quindi la stessa lettera riporta una lunghezza di 1 in Latin-1 e 2 in UTF-8. Questa espansione da singolo a doppio byte è esattamente ciò che permette al testo convertito di essere visualizzato correttamente in un contesto UTF-8.

Esempio 3: Conversione di testo ISO-8859-1 da XML

Supponiamo di avere un file XML dichiarato come ISO-8859-1 che si vuole leggere e convertire in UTF-8. È possibile usare la libreria SimpleXML per leggere il file e utf8_encode() per convertire ogni valore:

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

Questo codice carica un file XML dichiarato come ISO-8859-1 con simplexml_load_file(), itera su ogni elemento <item> e converte il testo di <title> e <description> in UTF-8 prima di stamparlo. (I valori SimpleXMLElement vengono convertiti in stringhe da utf8_encode().)

Quando usarla (e quando no)

Utilizzare utf8_encode() solo quando tutte queste condizioni sono vere:

• L'input è genuinamente ISO-8859-1 / Latin-1 (non Windows-1252, non già UTF-8).
• Si usa PHP 8.2 o precedente, dove la funzione esiste ancora.
• Si vuole una conversione rapida e senza dipendenze da Latin-1 a UTF-8.

Evitarla quando:

• L'origine potrebbe essere Windows-1252 (comune per testo da Windows / Excel). Windows-1252 riutilizza l'intervallo 0x80–0x9F per caratteri come € e virgolette tipografiche che ISO-8859-1 lascia non definiti — questi andrebbero persi o risulterebbero errati. Usare invece mb_convert_encoding($s, 'UTF-8', 'Windows-1252').
• Non si conosce la codifica dell'input. Rilevarla o dichiararla esplicitamente anziché indovinarla.
• Si punta a PHP 8.3+, dove la funzione è stata rimossa del tutto.

Alternative moderne

Poiché utf8_encode() è stata rimossa in PHP 8.3, è preferibile usare le funzioni multibyte-string o iconv, che consentono di specificare esplicitamente la codifica sorgente:

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

Entrambe producono gli stessi due byte (0xC3 0xA9) di utf8_encode(), ma rendono la codifica sorgente parte della chiamata — quindi funzionano anche per Windows-1252, ISO-8859-15 e decine di altre codifiche.

Funzioni correlate

• utf8_decode() — l'inverso: converte UTF-8 in ISO-8859-1.
• json_encode() — produce output UTF-8 e gestisce i caratteri multibyte.
• PHP Strings — panoramica su come lavorare con il testo in PHP.

Conclusione

utf8_encode() converte testo ISO-8859-1 (Latin-1) in UTF-8 ri-codificando ogni byte — trasformando i caratteri accentati a byte singolo nella loro forma UTF-8 a due byte. È comoda ma non rileva la codifica reale dell'input, ed è deprecata in PHP 8.2 e rimossa in PHP 8.3. Per qualsiasi nuovo codice, usare mb_convert_encoding() o iconv(), che consentono di specificare la codifica sorgente esplicitamente e gestiscono una gamma di set di caratteri molto più ampia.

Esercizio