htmlentities()

La funzione PHP htmlentities() converte ogni carattere che ha un'entità HTML con nome in quella entità. È lo strumento principale per stampare in modo sicuro testo non attendibile — come l'input dell'utente da un modulo — all'interno di una pagina HTML, perché trasforma i caratteri che il browser interpreterebbe altrimenti come markup (<, >, &, virgolette) in testo visibile innocuo. Questo la rende una prima linea di difesa contro il cross-site scripting (XSS).

Questa pagina tratta la sintassi, ciascuno dei quattro parametri, la differenza pratica rispetto a htmlspecialchars(), e i problemi comuni riguardanti la codifica e la doppia codifica.

Sintassi

htmlentities(
    string $string,
    int $flags = ENT_QUOTES | ENT_SUBSTITUTE | ENT_HTML401,
    ?string $encoding = null,
    bool $double_encode = true
): string

Restituisce una nuova stringa con i caratteri applicabili convertiti; la stringa originale non viene mai modificata.

Nota: A partire da PHP 8.1 i flag predefiniti sono ENT_QUOTES | ENT_SUBSTITUTE | ENT_HTML401. Su PHP 8.0 e versioni precedenti il valore predefinito era ENT_COMPAT | ENT_HTML401, che non codifica le virgolette singole. Se si supportano versioni precedenti, passare ENT_QUOTES esplicitamente.

Utilizzo di base

Questo produce:

Hello <strong>World</strong>!

I caratteri < e > diventano ora < e >, quindi il browser li visualizza come testo letterale invece di aprire un vero tag <strong>.

Il parametro $flags — gestione delle virgolette

Il secondo parametro controlla come vengono trattati i segni di virgolette. I flag più utili sono:

Usare ENT_QUOTES ogni volta che l'output potrebbe finire all'interno di un attributo HTML con virgolette singole, altrimenti un ' nei dati potrebbe uscire dall'attributo.

Output:

I'm a paragraph

La virgoletta singola diventa '. Con il vecchio valore predefinito ENT_COMPAT sarebbe rimasta come ' letterale.

Il parametro $encoding

Il terzo parametro indica a htmlentities() quale set di caratteri utilizza l'input, in modo da poter mappare correttamente i caratteri multibyte. Impostarlo sempre esplicitamente su "UTF-8" per le applicazioni moderne — una codifica errata può corrompere silenziosamente l'output o, nelle versioni precedenti di PHP, restituire una stringa vuota.

Output:

Café & «über»

Si noti come é, «, ü e » siano diventati ciascuno le loro entità con nome — questo è il comportamento che distingue htmlentities() da htmlspecialchars(), che lascerebbe quei caratteri accentati invariati.

Il parametro $double_encode

Per impostazione predefinita (true), htmlentities() ri-codifica il & in un'entità esistente, quindi < diventa <. Passare false per lasciare invariate le entità già codificate — utile quando parte della stringa è intenzionalmente pre-escapata.

Con $double_encode impostato su false, le entità esistenti passano attraverso invariate:

Hello <strong>World</strong>!

Se si fosse lasciato $double_encode al suo valore predefinito true, ogni & sarebbe stato ri-escapato in &, producendo Hello <strong>....

htmlentities() vs htmlspecialchars()

Questo è il punto di confusione più comune:

• htmlspecialchars() converte solo i cinque caratteri che hanno un significato speciale in HTML: &, <, >, " e '.
• htmlentities() converte quelli più ogni altro carattere che ha un'entità con nome (lettere accentate, simboli, segni di valuta e così via).

Per l'escape sicuro dell'output, htmlspecialchars() è di solito la scelta migliore: è più piccola, più veloce e — fintanto che si emette una pagina UTF-8 — i caratteri accentati vengono visualizzati correttamente da soli senza essere convertiti in entità. Ricorrere a htmlentities() solo quando si ha specificamente bisogno che ogni carattere mappabile in entità venga convertito, ad esempio quando si genera contenuto per una destinazione il cui charset non è possibile controllare.

Per invertire la conversione, usare html_entity_decode() o htmlspecialchars_decode().

Punti chiave

• htmlentities() restituisce una nuova stringa e non modifica mai l'originale.
• Passare sempre ENT_QUOTES e "UTF-8" esplicitamente per un output prevedibile e sicuro tra le versioni PHP.
• È un filtro di output — escapare i dati quando li si stampa, non quando li si memorizza.
• Per il tipico escape HTML, preferire htmlspecialchars().

Esercizio