xml_parser_set_option — Funktion · PHP-Referenz

Signatur

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

Beschreibung

xml_parser_set_option() ermöglicht es, das Verhalten eines XML-Parsers nachträglich zu konfigurieren. Die Funktion wird nach dem Erstellen des Parsers mit xml_parser_create() aufgerufen, um verschiedene Aspekte der XML-Verarbeitung zu steuern – etwa die Groß-/Kleinschreibung von Tag-Namen oder die Zielkodierung.

Die wichtigsten Optionen sind:

XML_OPTION_CASE_FOLDING (Standard: aktiviert) – wandelt Element-Namen in Großbuchstaben um. Kann auf 0 gesetzt werden, um die originale Schreibweise beizubehalten.
XML_OPTION_SKIP_TAGSTART – gibt an, wie viele Zeichen am Anfang eines Tag-Namens übersprungen werden sollen.
XML_OPTION_SKIP_WHITE – legt fest, ob Whitespace-only-Textelemente übersprungen werden.
XML_OPTION_TARGET_ENCODING – setzt die Zielkodierung der geparsten Strings (z. B. UTF-8, ISO-8859-1, US-ASCII).

Besonders häufig wird XML_OPTION_CASE_FOLDING deaktiviert, wenn XML-Dokumente verarbeitet werden, bei denen die Groß-/Kleinschreibung der Tag-Namen eine semantische Bedeutung hat. Die Standardeinstellung (Case Folding aktiv) kann sonst zu unerwarteten Ergebnissen führen, da z. B. <title> und <Title> beide als TITLE ankommen.

Diese Funktion gehört zur expat-basierten XML-Erweiterung und sollte nicht mit den SimpleXML- oder DOM-Erweiterungen verwechselt werden.

Parameter

Name	Typ	Beschreibung
$parser Pflicht	XMLParser	Eine Referenz auf den XML-Parser, dessen Option gesetzt werden soll. Der Parser muss zuvor mit `xml_parser_create()` oder `xml_parser_create_ns()` erstellt worden sein.
$option Pflicht	int	Die zu setzende Option als Konstante. Gültige Werte sind: `XML_OPTION_CASE_FOLDING`, `XML_OPTION_SKIP_TAGSTART`, `XML_OPTION_SKIP_WHITE` und `XML_OPTION_TARGET_ENCODING`.
$value Pflicht	string\|int\|bool	Der neue Wert für die Option. Für `XML_OPTION_CASE_FOLDING` und `XML_OPTION_SKIP_WHITE` wird ein boolescher oder ganzzahliger Wert erwartet. Für `XML_OPTION_TARGET_ENCODING` ein Kodierungs-String wie `'UTF-8'`. Für `XML_OPTION_SKIP_TAGSTART` eine ganze Zahl.

Rückgabewert

Typ

bool

Beschreibung

Gibt true zurück, wenn die Option erfolgreich gesetzt wurde, andernfalls false – zum Beispiel wenn eine ungültige Option oder ein ungültiger Wert angegeben wurde.

Beispiele

Case Folding deaktivieren, um originale Tag-Namen beizubehalten

<?php
$parser = xml_parser_create('UTF-8');

// Case Folding deaktivieren: Tag-Namen bleiben in ihrer Originalschreibweise
xml_parser_set_option($parser, XML_OPTION_CASE_FOLDING, 0);

$elementHandler = function (XMLParser $parser, string $name, array $attribs): void {
    // Ohne Case Folding: 'title' bleibt 'title', nicht 'TITLE'
    echo "Element: $name\n";
};

xml_set_element_handler($parser, $elementHandler, fn($p, $n) => null);

$xml = '<root><title>Hallo Welt</title><subItem>Test</subItem></root>';
xml_parse($parser, $xml, true);

xml_parser_free($parser);

Element: root Element: title Element: subItem

Whitespace-only-Knoten überspringen und Zielkodierung setzen

<?php
$parser = xml_parser_create();

// Leerzeichen-Textelemente überspringen
xml_parser_set_option($parser, XML_OPTION_SKIP_WHITE, 1);

// Zielkodierung auf ISO-8859-1 setzen
xml_parser_set_option($parser, XML_OPTION_TARGET_ENCODING, 'ISO-8859-1');

$charHandler = function (XMLParser $parser, string $data): void {
    $trimmed = trim($data);
    if ($trimmed !== '') {
        echo "Text: $trimmed\n";
    }
};

xml_set_character_data_handler($parser, $charHandler);

$xml = "<items>\n  <item>Erster</item>\n  <item>Zweiter</item>\n</items>";
xml_parse($parser, $xml, true);

xml_parser_free($parser);

Text: Erster Text: Zweiter

// Wichtig · Fallstricke

Case Folding (Standardverhalten): Standardmäßig ist XML_OPTION_CASE_FOLDING aktiviert, was bedeutet, dass alle Element- und Attributnamen in Großbuchstaben konvertiert werden. Wer auf die originale Schreibweise angewiesen ist, muss diese Option explizit deaktivieren.

Zielkodierung: Die Option XML_OPTION_TARGET_ENCODING unterstützt nur UTF-8, ISO-8859-1 und US-ASCII. Andere Kodierungen führen zu einem Fehler. Die Quellkodierung wird beim Erstellen des Parsers mit xml_parser_create() festgelegt und kann nicht nachträglich geändert werden.

PHP 8.0: Ab PHP 8.0 ist der erste Parameter vom Typ XMLParser (ein Objekt), in früheren Versionen war es eine Resource.

Siehe auch

xml_parser_create xml_parser_get_option xml_parser_free xml_parser_create_ns xml_set_element_handler