xml_parser_set_option()

La funzione xml_parser_set_option() è una funzione PHP integrata che imposta opzioni di configurazione su un parser XML. Appartiene all'estensione legacy XML Parser (Expat), che analizza XML in stile SAX — attivando callback di eventi durante la lettura — invece di costruire un albero in memoria come SimpleXML o DOM. Viene chiamata dopo xml_parser_create() ma prima dell'analisi, per controllare come il parser gestisce le maiuscole nei nomi dei tag, gli spazi bianchi e la codifica dei caratteri.

Sintassi

xml_parser_set_option(XMLParser $parser, int $option, string|int $value): bool

• $parser — il parser restituito da xml_parser_create(). Da PHP 8.0 è un oggetto XMLParser; in PHP 7 e versioni precedenti era una risorsa.
• $option — una delle costanti di opzione elencate di seguito.
• $value — il valore da impostare per quell'opzione.

La funzione restituisce true in caso di successo, oppure false se il parser o l'opzione non sono validi.

Opzioni disponibili

Leggi il valore corrente con xml_parser_get_option(). Impostare un'opzione dopo che l'analisi è iniziata non ha effetto, quindi configura il parser prima.

Perché il case folding è importante

Questa è l'opzione che userai più spesso. Per impostazione predefinita il parser converte in maiuscolo ogni nome di tag, quindi un elemento <note> arriva nel tuo gestore come NOTE. Questo sorprende chi confronta i nomi con stringhe in minuscolo. Disattivando il case folding i nomi vengono mantenuti esattamente come scritti:

$parser = xml_parser_create();

// Default behaviour: case folding ON → names arrive upper-cased
xml_set_element_handler($parser,
    fn($p, $name, $attrs) => print("Start: $name\n"),
    fn($p, $name) => null
);
xml_parse($parser, "<note><to>Tove</to></note>", true);
xml_parser_free($parser);

Output:

Start: NOTE
Start: TO

Impostando XML_OPTION_CASE_FOLDING a false, lo stesso input mantiene il caso originale (note, to).

Un esempio completo

L'estensione XML Parser è guidata da eventi: non succede nulla finché non vengono registrati i gestori e non gli viene fornita la stringa da analizzare. Questo esempio crea un parser, imposta due opzioni, registra i gestori di inizio/fine tag e analizza una stringa XML inline — senza file esterni, quindi puoi eseguirlo così com'è:

$parser = xml_parser_create();

// Keep the original tag case instead of upper-casing
xml_parser_set_option($parser, XML_OPTION_CASE_FOLDING, false);
// Drop elements that contain only whitespace
xml_parser_set_option($parser, XML_OPTION_SKIP_WHITE, true);

xml_set_element_handler(
    $parser,
    function ($parser, $name, $attrs) {
        echo "Start: $name\n";
    },
    function ($parser, $name) {
        echo "End: $name\n";
    }
);

$xml = "<note>\n  <to>Tove</to>\n  <from>Jani</from>\n</note>";
xml_parse($parser, $xml, true);

xml_parser_free($parser);

Output:

Start: note
Start: to
End: to
Start: from
End: from
End: note

Poiché il case folding è disattivato, i nomi dei tag mantengono la loro grafia in minuscolo. La chiamata a xml_set_element_handler() è ciò che permette a xml_parse() di emettere questi eventi; senza gestori registrati il parser leggerebbe il documento ma non produrrebbe alcun output. Chiama sempre xml_parser_free() quando hai finito per rilasciare il parser.

Quando usarlo

Usa xml_parser_set_option() solo quando stai già lavorando con il parser Expat di basso livello — tipicamente per l'analisi in streaming di documenti XML molto grandi in cui caricare l'intero albero in memoria non è desiderabile. Per la maggior parte delle attività quotidiane (lettura di configurazioni, consumo di una risposta API) usa SimpleXML, che è molto più semplice e non richiede questa configurazione.

Conclusione

xml_parser_set_option() configura il legacy parser XML in stile SAX — in particolare il comportamento di case folding, spazi bianchi e codifica. Imposta ogni opzione prima di chiamare xml_parse(), registra i gestori degli elementi affinché gli eventi vengano emessi, e libera il parser in seguito. Quando hai bisogno di un'elaborazione in streaming precisa e con poca memoria questa funzione ti offre quel controllo; altrimenti SimpleXML o DOM sono la scelta più semplice.

Pratica