htmlspecialchars()

La funzione htmlspecialchars() converte i pochi caratteri che hanno un significato speciale in HTML nelle corrispondenti entità HTML. Il suo scopo principale è la sicurezza: quando si visualizzano dati forniti dall'utente in una pagina web, passarli prima attraverso htmlspecialchars() impedisce che vengano interpretati come markup o script — la difesa standard contro gli attacchi di cross-site scripting (XSS).

Questa pagina illustra la sintassi della funzione, ciascuno dei suoi parametri con esempi eseguibili, i cinque caratteri che vengono modificati, le differenze rispetto alle funzioni correlate e come invertirne l'effetto in modo sicuro.

Sintassi

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

La funzione accetta un parametro obbligatorio, $string — la stringa da convertire — e tre parametri opzionali: $flags, $encoding e $double_encode. Restituisce la stringa convertita.

Nota sul flag predefinito. A partire da PHP 8.1 il valore predefinito di $flags è ENT_QUOTES | ENT_SUBSTITUTE | ENT_HTML401, che codifica sia le virgolette singole che quelle doppie. In PHP 8.0 e versioni precedenti il valore predefinito era ENT_COMPAT, che lasciava le virgolette singole invariate. Se si supportano versioni più vecchie, è sempre consigliabile passare ENT_QUOTES esplicitamente per garantire un comportamento prevedibile.

Quali caratteri vengono convertiti

Solo cinque caratteri sono interessati. Tutto il resto passa attraverso invariato:

Se è necessario codificare anche lettere accentate, simboli e altri caratteri non ASCII, usare htmlentities().

Esempio di base

Output:

Hello <strong>World</strong>!

I tag <strong> sono stati convertiti in <strong> e </strong>. Quando questa stringa viene inviata al browser, mostra il testo letterale <strong>World</strong> invece di renderizzare il markup in grassetto.

Il parametro $flags: gestione delle virgolette

Il secondo parametro, $flags, specifica come gestire le virgolette e quale tipo di documento utilizzare. La scelta più comune è ENT_QUOTES, che converte sia le virgolette singole (') che quelle doppie ("). Questo è importante quando si inserisce un valore all'interno di un attributo HTML, poiché una virgoletta non escapata potrebbe chiudere l'attributo prematuramente e iniettarne di nuovi.

Output:

I'm a paragraph

La virgoletta singola è stata convertita in '. I valori di flag più comuni sono:

• ENT_QUOTES — converte sia le virgolette doppie che quelle singole (consigliato).
• ENT_COMPAT — converte le virgolette doppie, lascia invariate quelle singole.
• ENT_NOQUOTES — lascia entrambi i tipi di virgolette non convertiti.
• ENT_SUBSTITUTE — sostituisce le sequenze di unità di codice non valide con � invece di restituire una stringa vuota.

Il parametro $encoding

Il terzo parametro, $encoding, indica la codifica dei caratteri della stringa di input. Il valore predefinito è quello dell'impostazione INI default_charset (UTF-8 nelle installazioni moderne). Specificarlo esplicitamente evita sorprese se l'input è in una codifica diversa.

Output:

Tom & Jerry

In questo caso la e commerciale viene codificata come & mentre PHP interpreta l'input come UTF-8. Se la codifica non corrisponde ai byte effettivi di $string, la funzione potrebbe restituire una stringa vuota (o un carattere di sostituzione quando ENT_SUBSTITUTE è impostato).

Il parametro $double_encode

Il quarto parametro, $double_encode, controlla se le entità esistenti vengono codificate nuovamente. Per impostazione predefinita è true, quindi una stringa che contiene già < diventa <. Impostarlo a false lascia intatte le entità già codificate — utile quando l'input è già stato parzialmente escapato.

Output:

Hello <strong>World</strong>!

Le entità < e > esistenti rimangono invariate perché $double_encode è false. Con il valore predefinito true, lo stesso input avrebbe prodotto Hello <strong>....

Prevenire XSS in pratica

L'utilizzo più importante di htmlspecialchars() è l'escaping di qualsiasi dato che non si controlla completamente — input da form, valori della query string, record del database originati dagli utenti — prima di visualizzarli in una pagina:

<?php
$comment = $_GET['comment'] ?? '';   // e.g. "<script>alert('xss')</script>"
echo "<p>" . htmlspecialchars($comment, ENT_QUOTES, "UTF-8") . "</p>";
?>

Il tag <script> viene neutralizzato in <script>...</script>, in modo che il browser mostri il testo invece di eseguirlo. Applicare l'escaping al momento dell'output, non durante la memorizzazione dei dati, in modo che il valore grezzo rimanga disponibile per altri contesti.

Invertire la conversione

Per riconvertire le entità nei caratteri originali, usare htmlspecialchars_decode(). Passare gli stessi flag usati durante la codifica in modo che le virgolette vengano gestite simmetricamente.

Funzioni correlate

• htmlentities() — come htmlspecialchars() ma converte tutti i caratteri che hanno equivalenti come entità HTML, non solo i cinque speciali.
• htmlspecialchars_decode() — la funzione inversa di questa.
• strip_tags() — rimuove completamente i tag HTML e PHP invece di escaparli.
• nl2br() — inserisce <br> prima dei caratteri di nuova riga, spesso usato dopo aver escapato il testo normale.

Riepilogo

Usare htmlspecialchars() ogni volta che si visualizza testo non attendibile in HTML. Passare ENT_QUOTES e una codifica UTF-8 esplicita per risultati prevedibili e sicuri tra le versioni di PHP, escapare al momento dell'output e ricorrere a htmlentities() solo quando è necessario codificare ogni entità anziché soltanto i cinque caratteri speciali.

Pratica