xmlwriter_start_pi — Funktion · PHP-Referenz

Signatur

xmlwriter_start_pi(XMLWriter $writer, string $target): bool

Beschreibung

Eine XML-Verarbeitungsanweisung (Processing Instruction, kurz PI) ist eine spezielle XML-Konstruktion der Form <?ziel inhalt?>, die Anweisungen für eine Anwendung oder einen Prozessor einbettet, ohne zum eigentlichen Dokumentinhalt zu gehören. Typische Beispiele sind PHP-Tags (<?php ... ?>), XML-Stylesheet-Verknüpfungen (<?xml-stylesheet ...?>) oder prozessorspezifische Direktiven.

xmlwriter_start_pi öffnet eine solche Anweisung. Nach dem Aufruf kann der Inhalt der Verarbeitungsanweisung mit xmlwriter_text geschrieben werden. Abgeschlossen wird die Anweisung mit xmlwriter_end_pi. Ohne abschließenden Aufruf von xmlwriter_end_pi bleibt die PI im Stream offen und das erzeugte XML ist ungültig.

Die prozedurale Variante erwartet ein XMLWriter-Objekt als erstes Argument. In der objektorientierten API steht die entsprechende Methode XMLWriter::startPi() zur Verfügung. Der $target-Parameter darf nicht xml (Groß-/Kleinschreibung egal) sein, da dieser Name für die XML-Deklaration reserviert ist.

Parameter

Name	Typ	Default	Beschreibung
$writer Pflicht	XMLWriter		Das `XMLWriter`-Objekt, in das geschrieben wird. Es muss zuvor mit `xmlwriter_open_uri` oder `xmlwriter_open_memory` erstellt worden sein.
$target Pflicht	string		Der Ziel-Name der Verarbeitungsanweisung, z. B. `php` oder `xml-stylesheet`. Der Name muss ein gültiger XML-Name sein und darf nicht (in beliebiger Groß-/Kleinschreibung) `xml` lauten.

Rückgabewert

Typ

bool

Beschreibung

Gibt true bei Erfolg zurück, false bei einem Fehler (z. B. ungültiger Ziel-Name oder nicht geöffnetem Writer).

Beispiele

XML-Stylesheet-Verarbeitungsanweisung erzeugen

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

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

// Verarbeitungsanweisung für Stylesheet
xmlwriter_start_pi($writer, 'xml-stylesheet');
xmlwriter_text($writer, 'type="text/xsl" href="style.xsl"');
xmlwriter_end_pi($writer);

// Wurzelelement
xmlwriter_start_element($writer, 'root');
xmlwriter_text($writer, 'Inhalt');
xmlwriter_end_element($writer);

xmlwriter_end_document($writer);

echo xmlwriter_output_memory($writer);

<?xml version="1.0" encoding="UTF-8"?> <?xml-stylesheet type="text/xsl" href="style.xsl"?> <root>Inhalt</root>

Benutzerdefinierte PHP-Verarbeitungsanweisung einfügen

<?php
$writer = xmlwriter_open_memory();
xmlwriter_start_document($writer, '1.0', 'UTF-8');

// Eigene PI für eine Applikation
xmlwriter_start_element($writer, 'data');

xmlwriter_start_pi($writer, 'myapp');
xmlwriter_text($writer, 'action="transform" mode="full"');
xmlwriter_end_pi($writer);

xmlwriter_start_element($writer, 'item');
xmlwriter_text($writer, 'Beispielwert');
xmlwriter_end_element($writer);

xmlwriter_end_element($writer);
xmlwriter_end_document($writer);

echo xmlwriter_output_memory($writer);

<?xml version="1.0" encoding="UTF-8"?> <data><?myapp action="transform" mode="full"?><item>Beispielwert</item></data>

// Wichtig · Fallstricke

Reservierter Name: Der Ziel-Name darf nicht xml, XML oder eine Groß-/Kleinschreibvariante davon sein, da dieser Name gemäß XML-Spezifikation für die XML-Deklaration reserviert ist. Ein solcher Versuch führt dazu, dass xmlwriter_start_pi false zurückgibt.

Paarigkeit beachten: Jeder Aufruf von xmlwriter_start_pi muss zwingend mit einem Aufruf von xmlwriter_end_pi abgeschlossen werden, sonst ist das produzierte XML-Dokument nicht wohlgeformt.

Die objektorientierte Alternative lautet $writer->startPi($target) und $writer->endPi().

Siehe auch

xmlwriter_end_pi xmlwriter_start_document xmlwriter_text xmlwriter_open_memory xmlwriter_open_uri