xml_parser_get_option()

La funzione xml_parser_get_option() legge il valore corrente di un'opzione di configurazione su un parser XML creato con l'estensione xml basata su Expat. Ogni parser mantiene un piccolo insieme di opzioni (case folding, codifica di destinazione e salto degli spazi bianchi) che controllano come converte il markup grezzo in eventi. Le si imposta con xml_parser_set_option() e le si rilegge con xml_parser_get_option().

In pratica la si usa per verificare la configurazione di un parser prima di avviare il parsing — ad esempio, per controllare se il case folding è ancora attivo, o per registrare quale codifica di destinazione produrrà un parser. È il complemento in sola lettura del setter e non modifica mai il parser.

Questa pagina illustra la firma della funzione, le opzioni che è possibile interrogare (e i loro valori predefiniti), un esempio eseguibile e le insidie da conoscere — incluso il fatto che Expat è un'API di basso livello che la maggior parte dei progetti non utilizza più direttamente.

Sintassi

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

$parser è l'handle del parser restituito da xml_parser_create() (a partire da PHP 8.0 si tratta di un oggetto XMLParser anziché di una resource). $option è una delle costanti XML_OPTION_* elencate di seguito. Il tipo restituito dipende dall'opzione: un boolean per i flag on/off, un intero per XML_OPTION_SKIP_TAGSTART e una stringa per XML_OPTION_TARGET_ENCODING.

Opzioni disponibili

L'interrogazione di un'opzione sconosciuta restituisce false.

Esempi

Lettura di una singola opzione

Questo crea un parser, disabilita il case folding, quindi rilegge l'opzione. Poiché viene restituito false, il messaggio riporta "disabled":

<?php
$parser = xml_parser_create();
xml_parser_set_option($parser, XML_OPTION_CASE_FOLDING, false);

$caseFolding = xml_parser_get_option($parser, XML_OPTION_CASE_FOLDING);
echo "Case folding is " . ($caseFolding ? "enabled" : "disabled") . ".\n";

Output:

Case folding is disabled.

Ispezione dei valori predefiniti e verifica delle modifiche

Un parser appena creato ha già valori predefiniti ragionevoli. Leggerli prima e dopo una chiamata a set è un buon modo per verificare che la configurazione abbia avuto effetto:

<?php
$parser = xml_parser_create();

// Defaults on a brand-new parser.
echo "Default case folding: ";
var_dump(xml_parser_get_option($parser, XML_OPTION_CASE_FOLDING));   // bool(true)
echo "Default encoding: ";
var_dump(xml_parser_get_option($parser, XML_OPTION_TARGET_ENCODING)); // string(5) "UTF-8"

// Change two options, then confirm them.
xml_parser_set_option($parser, XML_OPTION_CASE_FOLDING, false);
xml_parser_set_option($parser, XML_OPTION_SKIP_WHITE, true);

printf("Case folding now: %s\n", xml_parser_get_option($parser, XML_OPTION_CASE_FOLDING) ? "on" : "off");
printf("Skip whitespace:  %s\n", xml_parser_get_option($parser, XML_OPTION_SKIP_WHITE) ? "on" : "off");

Output:

Default case folding: bool(true)
Default encoding: string(5) "UTF-8"
Case folding now: off
Skip whitespace:  on

Impostare prima le opzioni, verificarle con xml_parser_get_option() se lo si desidera, e solo poi fornire i dati a xml_parse(). Una volta avviato il parsing, non è più consentito modificare le opzioni di case folding o di codifica.

Note e insidie

• Legge soltanto. Questa funzione non modifica mai il parser. Per modificare un'opzione, utilizzare xml_parser_set_option().
• Restituisce tipi misti. Gestire il risultato in base all'opzione: un flag bool, un int per SKIP_TAGSTART o una stringa per la codifica. Non assumere un boolean per ogni opzione.
• Expat è di basso livello e datato. L'estensione xml (Expat) precede le API moderne. A meno che non sia necessario specificamente il parsing basato su eventi ("SAX") di documenti molto grandi, SimpleXML o DOM sono di solito più semplici e sicuri. Da notare che XML_OPTION_CASE_FOLDING con valore predefinito true è la sorpresa classica: i nomi degli elementi arrivano in maiuscolo a meno che non lo si disabiliti.
• Liberare il parser al termine. Sebbene PHP liberi l'oggetto XMLParser autonomamente, è possibile chiamare xml_parser_free() per rilasciarlo esplicitamente.

Conclusione

xml_parser_get_option() è la metà getter della coppia di opzioni del parser Expat: restituisce il valore corrente di XML_OPTION_CASE_FOLDING, XML_OPTION_TARGET_ENCODING, XML_OPTION_SKIP_WHITE o XML_OPTION_SKIP_TAGSTART senza modificare nulla. Usarla per confermare la configurazione di un parser prima di chiamare xml_parse(). Per il nuovo codice che non necessita di parsing SAX di basso livello, preferire SimpleXML o l'estensione DOM.

Esercizio