xml_set_start_namespace_decl_handler()

Die Funktion xml_set_start_namespace_decl_handler() registriert einen Callback, den der XML-Parser jedes Mal aufruft, wenn er den Beginn einer Namespace-Deklaration findet — also ein xmlns- oder xmlns:prefix-Attribut, das einen Namespace in den Gültigkeitsbereich bringt. Sie gehört zur Low-Level-, ereignisgesteuerten XML Parser (SAX)-Erweiterung von PHP und hat nichts mit SimpleXML oder DOM zu tun, die das gesamte Dokument in einen Baum parsen, anstatt Ereignisse zu streamen.

Dieser Handler wird benötigt, wenn große oder gestreamte XML-Dokumente geparst werden und bekannt sein soll, welche Namespaces aktiv sind — etwa um Präfixe auf URIs abzubilden, zu prüfen, ob ein erforderlicher Namespace vorhanden ist, oder Elemente je nach Namespace an verschiedene Verarbeitungsroutinen weiterzuleiten.

Wichtige Voraussetzung: Namespace-Handler werden nur ausgelöst, wenn der Parser namespace-fähig ist. Der Parser muss mit xml_parser_create_ns() erstellt werden, nicht mit xml_parser_create(). Ein einfacher Parser ignoriert xmlns-Attribute stillschweigend, sodass dieser Handler niemals aufgerufen wird.

Syntax

xml_set_start_namespace_decl_handler($parser, $handler): bool

Die Funktion gibt bei Erfolg true zurück, bei Misserfolg false.

Die Callback-Signatur

Der Handler erhält drei Argumente:

function handler($parser, $prefix, $uri): void

• $parser — der Parser, der das Ereignis ausgelöst hat.
• $prefix — das Namespace-Präfix, z. B. "ns" für xmlns:ns="…". Bei einem Standard-Namespace (xmlns="…") ist das Präfix der boolean false, nicht ein leerer string.
• $uri — die Namespace-URI, an die das Präfix gebunden ist.

Beispiel: Namespace-Deklarationen lesen

Das folgende Beispiel parst ein Atom-ähnliches Dokument mit zwei Namespaces und gibt jeden aus, sobald er in den Gültigkeitsbereich kommt. Beachten Sie die Verwendung von xml_parser_create_ns(), damit die Ereignisse tatsächlich ausgelöst werden:

function handleStartNamespace($parser, $prefix, $uri) {
    // A default namespace (xmlns="...") arrives as prefix === false.
    $name = ($prefix === false) ? "(default)" : $prefix;
    echo "Namespace in scope -> $name = $uri\n";
}

$parser = xml_parser_create_ns();
xml_set_start_namespace_decl_handler($parser, "handleStartNamespace");

$xml = '<?xml version="1.0"?>
<root xmlns:ns="http://example.com/ns"
      xmlns:meta="http://example.com/meta">
  <ns:item>Test</ns:item>
</root>';

// The third argument `true` marks this as the final chunk of data.
xml_parse($parser, $xml, true);
xml_parser_free($parser);

Ausgabe:

Namespace in scope -> ns = http://example.com/ns
Namespace in scope -> meta = http://example.com/meta

Der Parser löst für jeden deklarierten Namespace ein Ereignis aus, in der Reihenfolge, in der die xmlns-Attribute erscheinen, bevor er das Element meldet, das sie deklariert hat.

Häufige Fallstricke

• Einfacher Parser, keine Ereignisse. Wenn der Parser mit xml_parser_create() statt xml_parser_create_ns() erstellt wird, wird der Handler niemals aufgerufen und es erscheint keine Ausgabe — eine häufige Ursache für „es funktioniert nicht"-Verwirrung.
• Standard-Namespace-Präfix ist false. Immer mit === vergleichen ($prefix === false); ein if (!$prefix)-Test trifft auch das gültige Präfix "0".
• Mit dem End-Handler kombinieren. Der zugehörige xml_set_end_namespace_decl_handler() markiert, wo ein Namespace wieder außer Gültigkeitsbereich tritt, was wichtig ist, wenn Verschachtelungen verfolgt werden.
• Parser freigeben. Rufen Sie xml_parser_free() auf, wenn Sie fertig sind, um die Ressource freizugeben.

Verwandte Funktionen

• xml_parser_create_ns() — erstellt den namespace-fähigen Parser, den dieser Handler benötigt.
• xml_set_end_namespace_decl_handler() — der passende Handler für das Ende des Gültigkeitsbereichs.
• xml_set_element_handler() — behandelt Start- und End-Tags von Elementen.
• xml_parse() — übergibt Daten an den Parser und löst die Callbacks aus.

Fazit

xml_set_start_namespace_decl_handler() ermöglicht es, auf Namespaces zu reagieren, sobald sie beim Streaming von XML mit dem SAX-Parser in den Gültigkeitsbereich kommen. Das einzige, worüber Entwickler häufig stolpern, ist der Parser: Namespace-Ereignisse werden nur ausgelöst, wenn der Parser mit xml_parser_create_ns() erstellt wurde. Zu beachten ist, dass ein Standard-Namespace mit dem Präfix false ankommt, der Handler mit xml_set_end_namespace_decl_handler() kombiniert werden sollte, wenn das Namespace-Scoping verfolgt werden soll, und der Parser am Ende freigegeben werden muss.

Übungen