xmlwriter_start_element_ns — Funktion · PHP-Referenz

Signatur

xmlwriter_start_element_ns(XMLWriter $writer, ?string $prefix, string $name, ?string $namespace): bool

Beschreibung

xmlwriter_start_element_ns() öffnet ein neues XML-Element und versieht es mit einem Namensraum-Präfix sowie einem Namensraum-URI. Dies ist nützlich, wenn man XML-Dokumente erzeugt, die mehrere Namensräume (z. B. SOAP, Atom, SVG) enthalten, und Elemente eindeutig einem Namensraum zuordnen möchte.

Das erzeugte Element erhält die Form <präfix:name xmlns:präfix="namensraum">. Wird null als Präfix übergeben, wird kein Präfix genutzt, aber der Namensraum als Standardnamensraum (xmlns="...") deklariert. Wird null als Namensraum übergeben, wird kein Namespace-Attribut geschrieben.

Die Funktion arbeitet prozedural auf einem XMLWriter-Handle. Sie muss stets mit xmlwriter_end_element() oder xmlwriter_full_end_element() abgeschlossen werden, damit das resultierende XML wohlgeformt ist.

Für die objektorientierte API steht die äquivalente Methode XMLWriter::startElementNs() zur Verfügung.

Parameter

Name	Typ	Beschreibung
$writer Pflicht	XMLWriter	Das `XMLWriter`-Objekt, das durch `xmlwriter_open_memory()` oder `xmlwriter_open_uri()` erzeugt wurde.
$prefix Pflicht	?string	Das Namensraum-Präfix (z. B. `'soap'`). Bei `null` wird kein Präfix gesetzt und der Namensraum als Standardnamensraum deklariert.
$name Pflicht	string	Der lokale Name des Elements (z. B. `'Body'`). Darf keine Leerzeichen oder ungültige XML-Zeichen enthalten.
$namespace Pflicht	?string	Der vollständige Namensraum-URI (z. B. `'http://schemas.xmlsoap.org/soap/envelope/'`). Bei `null` wird kein `xmlns`-Attribut geschrieben.

Rückgabewert

Typ

bool

Beschreibung

Gibt true bei Erfolg zurück, false bei einem Fehler (z. B. ungültigem Element-Namen oder nicht initialisiertem Writer).

Beispiele

Einfaches SOAP-Envelope-Dokument mit Namensräumen

<?php
$writer = xmlwriter_open_memory();
xmlwriter_set_indent($writer, true);
xmlwriter_set_indent_string($writer, '  ');

xmlwriter_start_document($writer, '1.0', 'UTF-8');

// <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
xmlwriter_start_element_ns(
    $writer,
    'soap',
    'Envelope',
    'http://schemas.xmlsoap.org/soap/envelope/'
);

// <soap:Body>
xmlwriter_start_element_ns($writer, 'soap', 'Body', null);

// <soap:Fault>
xmlwriter_start_element_ns($writer, 'soap', 'Fault', null);
xmlwriter_write_element($writer, 'faultcode', 'Server');
xmlwriter_write_element($writer, 'faultstring', 'Internal Server Error');
xmlwriter_end_element($writer); // soap:Fault

xmlwriter_end_element($writer); // soap:Body
xmlwriter_end_element($writer); // soap:Envelope

xmlwriter_end_document($writer);

echo xmlwriter_output_memory($writer);

<?xml version="1.0" encoding="UTF-8"?> <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"> <soap:Body> <soap:Fault> <faultcode>Server</faultcode> <faultstring>Internal Server Error</faultstring> </soap:Fault> </soap:Body> </soap:Envelope>

Standardnamensraum ohne Präfix setzen

<?php
$writer = xmlwriter_open_memory();
xmlwriter_set_indent($writer, true);

xmlwriter_start_document($writer, '1.0', 'UTF-8');

// <feed xmlns="http://www.w3.org/2005/Atom">
xmlwriter_start_element_ns(
    $writer,
    null,
    'feed',
    'http://www.w3.org/2005/Atom'
);

xmlwriter_write_element($writer, 'title', 'Mein Atom-Feed');
xmlwriter_write_element($writer, 'id', 'urn:uuid:12345');

xmlwriter_end_element($writer); // feed
xmlwriter_end_document($writer);

echo xmlwriter_output_memory($writer);

<?xml version="1.0" encoding="UTF-8"?> <feed xmlns="http://www.w3.org/2005/Atom"> <title>Mein Atom-Feed</title> <id>urn:uuid:12345</id> </feed>

// Wichtig · Fallstricke

Namensraum-Deklaration: Der Namensraum-URI wird nur beim ersten Auftreten eines Präfixes als xmlns:präfix-Attribut in das Dokument geschrieben. Bei weiteren Elementen mit demselben Präfix und null als Namensraum wird kein redundantes Attribut erzeugt – das ist das korrekte Verhalten.

Wohlgeformtheit: Jedes mit xmlwriter_start_element_ns() geöffnete Element muss mit xmlwriter_end_element() oder xmlwriter_full_end_element() geschlossen werden, sonst ist das resultierende XML ungültig.

OOP-Äquivalent: In der objektorientierten Variante lautet der Aufruf $writer->startElementNs($prefix, $name, $namespace).

Siehe auch

xmlwriter_end_element xmlwriter_write_element_ns xmlwriter_start_attribute_ns xmlwriter_start_element xmlwriter_open_memory xmlwriter_output_memory