html_entity_decode()

La funzione PHP html_entity_decode() converte le entità HTML (come <, & o ©) nei caratteri corrispondenti (<, &, ©). È l'inverso di htmlentities(), ed è la funzione a cui ricorrere ogni volta che è necessario trasformare HTML già codificato in testo leggibile — ad esempio, quando si leggono dati memorizzati in forma codificata o quando si elabora l'output di un sistema che ha eseguito l'escape del proprio HTML.

Questa pagina illustra la sintassi, i singoli parametri, i flag che controllano la gestione delle virgolette e le insidie più comuni (in particolare quelle legate alla sicurezza).

Sintassi

html_entity_decode(
    string $string,
    int $flags = ENT_QUOTES | ENT_SUBSTITUTE | ENT_HTML401,
    ?string $encoding = null
): string

La funzione restituisce la stringa decodificata. A partire da PHP 8.1, il valore predefinito di $flags è ENT_QUOTES | ENT_SUBSTITUTE | ENT_HTML401; le versioni precedenti utilizzavano ENT_COMPAT | ENT_HTML401.

Esempio di base

Le entità < e > vengono riconvertite in < e >, quindi l'output è:

<h1>Hello World</h1>

Controllo delle virgolette con $flags

Il parametro $flags determina come vengono trattate le virgolette singole e doppie:

Aggiungere ENT_HTML401, ENT_HTML5, ENT_XML1 o ENT_XHTML per selezionare il set di entità, e ENT_SUBSTITUTE/ENT_IGNORE per controllare la gestione delle sequenze di byte non valide. Usare ENT_QUOTES quando l'input potrebbe contenere virgolette singole codificate (' / '):

Con ENT_QUOTES, vengono ripristinati sia i tag che la virgoletta singola codificata:

<p>I'm a paragraph</p>

Specificare la codifica dei caratteri

Il terzo parametro, $encoding, indica a PHP come interpretare i byte di input. Il valore predefinito è l'impostazione ini default_charset. È necessario specificarlo esplicitamente quando non è possibile fare affidamento su quel valore predefinito — nella maggior parte dei casi "UTF-8":

ENT_HTML5 consente a PHP di riconoscere il set completo di entità con nome HTML5, quindi é e & vengono decodificate in:

Café & Co.

Sicurezza: non decodificare prima dell'output

html_entity_decode() è l'opposto dell'escape. Decodificare contenuto fornito dall'utente e poi stamparlo in una pagina reintroduce qualsiasi tag <script> o attributo rimosso dall'escape, aprendo una vulnerabilità XSS. Decodificare solo quando si hanno bisogno dei caratteri grezzi per scopi non HTML (logging, confronto, generazione di una versione in testo semplice, creazione di un PDF, ecc.). Quando si stampa in HTML, mantenere i dati con l'escape applicato.

Funzioni correlate

• htmlentities() — l'inverso: converte i caratteri in entità HTML.
• htmlspecialchars() — applica l'escape solo ai cinque caratteri HTML speciali (<, >, &, ", ').
• htmlspecialchars_decode() — inverte htmlspecialchars(); più veloce di html_entity_decode() quando si ha bisogno di recuperare solo quei cinque caratteri.

html_entity_decode() gestisce il set completo di entità con nome, quindi va usata quando l'input potrebbe contenere entità come © o é; ricorrere a htmlspecialchars_decode() quando si è prodotto output esclusivamente con htmlspecialchars().

Esercitazione