xml_parser_get_option()

La fonction xml_parser_get_option() lit la valeur actuelle d'une option de configuration sur un parseur XML créé avec l'extension xml basée sur Expat. Chaque parseur dispose d'un petit ensemble d'options (repli de casse, encodage cible et omission des espaces blancs) qui contrôlent la façon dont il transforme le balisage brut en événements. Vous les définissez avec xml_parser_set_option() ; vous les relisez avec xml_parser_get_option().

En pratique, vous y avez recours pour confirmer la configuration d'un parseur avant de démarrer l'analyse — par exemple, pour vérifier si le repli de casse est encore actif, ou pour journaliser l'encodage cible qu'un parseur va produire. C'est le complément en lecture seule du setter et il ne modifie jamais le parseur.

Cette page couvre la signature de la fonction, les options que vous pouvez interroger (ainsi que leurs valeurs par défaut), un exemple exécutable et les pièges à connaître — notamment le fait qu'Expat est une API bas niveau que la plupart des projets n'utilisent plus directement.

Syntaxe

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

$parser est le handle du parseur retourné par xml_parser_create() (depuis PHP 8.0, il s'agit d'un objet XMLParser plutôt que d'une resource). $option est l'une des constantes XML_OPTION_* ci-dessous. Le type de retour dépend de l'option : un booléen pour les indicateurs actif/inactif, un entier pour XML_OPTION_SKIP_TAGSTART, et une chaîne pour XML_OPTION_TARGET_ENCODING.

Options disponibles

L'interrogation d'une option inconnue renvoie false.

Exemples

Lecture d'une seule option

Ceci crée un parseur, désactive le repli de casse, puis relit l'option. Comme false est retourné, le message indique « 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";

Résultat :

Case folding is disabled.

Inspection des valeurs par défaut et confirmation des modifications

Un nouveau parseur dispose déjà de valeurs par défaut raisonnables. Les lire avant et après un appel à set est un bon moyen de vérifier que votre configuration a bien pris effet :

<?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");

Résultat :

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

Définissez vos options en premier, vérifiez-les avec xml_parser_get_option() si vous le souhaitez, puis seulement transmettez des données à xml_parse(). Une fois l'analyse commencée, la modification des options de repli de casse ou d'encodage n'est plus autorisée.

Remarques et pièges

• Elle ne fait que lire. Cette fonction ne modifie jamais le parseur. Pour modifier une option, utilisez xml_parser_set_option().
• Retourne des types mixtes. Traitez le résultat selon l'option : un indicateur booléen, un entier pour SKIP_TAGSTART, ou une chaîne pour l'encodage. Ne supposez pas un booléen pour chaque option.
• Expat est bas niveau et vieillissant. L'extension xml (Expat) est antérieure aux API modernes. Sauf si vous avez spécifiquement besoin d'une analyse basée sur les événements (« SAX ») de très grands documents, SimpleXML ou DOM sont généralement plus faciles et plus sûrs. Notez que XML_OPTION_CASE_FOLDING valant true par défaut est la surprise classique : les noms d'éléments arrivent en majuscules sauf si vous le désactivez.
• Libérez le parseur lorsque vous avez terminé. Bien que PHP libère l'objet XMLParser de lui-même, vous pouvez appeler xml_parser_free() pour le libérer explicitement.

Conclusion

xml_parser_get_option() est la moitié getter de la paire d'options du parseur Expat : elle retourne la valeur actuelle de XML_OPTION_CASE_FOLDING, XML_OPTION_TARGET_ENCODING, XML_OPTION_SKIP_WHITE ou XML_OPTION_SKIP_TAGSTART sans rien modifier. Utilisez-la pour confirmer la configuration d'un parseur avant d'appeler xml_parse(). Pour le nouveau code qui n'a pas besoin d'une analyse SAX bas niveau, préférez SimpleXML ou l'extension DOM.

Pratique