xml_parser_get_option()

Die Funktion xml_parser_get_option() liest den aktuellen Wert einer Konfigurationsoption eines XML-Parsers aus, der mit der veralteten Expat-basierten xml-Erweiterung erstellt wurde. Jeder Parser verfügt über eine kleine Menge von Optionen (Case Folding, Zielkodierung und Whitespace-Überspringen), die steuern, wie er rohes Markup in Ereignisse umwandelt. Diese werden mit xml_parser_set_option() gesetzt und mit xml_parser_get_option() wieder ausgelesen.

In der Praxis verwendet man sie, um die Konfiguration eines Parsers zu überprüfen, bevor mit dem Parsen begonnen wird – zum Beispiel, um zu prüfen, ob Case Folding noch aktiviert ist, oder um zu protokollieren, welche Zielkodierung ein Parser verwenden wird. Sie ist das schreibgeschützte Gegenstück zum Setter und verändert den Parser nie.

Diese Seite behandelt die Signatur der Funktion, die abfragbaren Optionen (und ihre Standardwerte), ein ausführbares Beispiel sowie wichtige Fallstricke – einschließlich der Tatsache, dass Expat eine Low-Level-API ist, auf die die meisten Projekte heute nicht mehr direkt zugreifen.

Syntax

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

$parser ist das Parser-Handle, das von xml_parser_create() zurückgegeben wird (seit PHP 8.0 handelt es sich dabei um ein XMLParser-Objekt statt einer resource). $option ist eine der unten aufgeführten XML_OPTION_*-Konstanten. Der Rückgabetyp hängt von der Option ab: ein Boolean für die Ein/Aus-Flags, ein Integer für XML_OPTION_SKIP_TAGSTART und ein String für XML_OPTION_TARGET_ENCODING.

Verfügbare Optionen

Die Abfrage einer unbekannten Option gibt false zurück.

Beispiele

Eine einzelne Option auslesen

Dieses Beispiel erstellt einen Parser, deaktiviert Case Folding und liest die Option anschließend wieder aus. Da false zurückgegeben wird, meldet die Ausgabe "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";

Ausgabe:

Case folding is disabled.

Standardwerte prüfen und Änderungen bestätigen

Ein neuer Parser hat bereits sinnvolle Standardwerte. Diese vor und nach einem set-Aufruf auszulesen ist eine gute Möglichkeit zu überprüfen, ob die Konfiguration wirksam wurde:

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

Ausgabe:

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

Setzen Sie zuerst Ihre Optionen, überprüfen Sie diese bei Bedarf mit xml_parser_get_option() und geben Sie erst dann Daten an xml_parse() weiter. Sobald das Parsen begonnen hat, ist eine Änderung der Case-Folding- oder Kodierungsoptionen nicht mehr möglich.

Hinweise und Fallstricke

• Nur zum Lesen. Diese Funktion verändert den Parser nie. Um eine Option zu ändern, verwenden Sie xml_parser_set_option().
• Gibt gemischte Typen zurück. Behandeln Sie das Ergebnis je nach Option: ein bool-Flag, ein Integer für SKIP_TAGSTART oder ein String für die Kodierung. Gehen Sie nicht bei jeder Option von einem Boolean aus.
• Expat ist Low-Level und veraltet. Die xml-Erweiterung (Expat) ist älter als moderne APIs. Sofern Sie nicht explizit ereignisbasiertes ("SAX") Parsen sehr großer Dokumente benötigen, sind SimpleXML oder DOM in der Regel einfacher und sicherer. Beachten Sie, dass XML_OPTION_CASE_FOLDING standardmäßig true ist – Element-Namen kommen in Großbuchstaben an, bis man das deaktiviert.
• Parser nach der Verwendung freigeben. Obwohl PHP das XMLParser-Objekt selbst freigibt, können Sie xml_parser_free() aufrufen, um es explizit freizugeben.

Fazit

xml_parser_get_option() ist die Lese-Hälfte des Optionspaars des Expat-Parsers: Sie gibt den aktuellen Wert von XML_OPTION_CASE_FOLDING, XML_OPTION_TARGET_ENCODING, XML_OPTION_SKIP_WHITE oder XML_OPTION_SKIP_TAGSTART zurück, ohne etwas zu verändern. Verwenden Sie sie, um die Konfiguration eines Parsers zu bestätigen, bevor Sie xml_parse() aufrufen. Für neuen Code, der kein Low-Level-SAX-Parsen benötigt, empfiehlt sich stattdessen SimpleXML oder die DOM-Erweiterung.

Übungen