xml_set_processing_instruction_handler()

Die Funktion xml_set_processing_instruction_handler() legt eine benutzerdefinierte Funktion als Handler für Verarbeitungsanweisungen in einem XML-Parser fest. Sie gehört zur veralteten xml-Erweiterung (Expat / SAX) und wird für die ereignisbasierte Verarbeitung verwendet, nicht für die SimpleXML-Bibliothek. Immer wenn der Parser eine Verarbeitungsanweisung im Dokument erreicht, ruft er Ihren Handler auf, damit Sie darauf reagieren können – zum Beispiel um eingebettete Direktiven zu extrahieren oder eine Aktion mitten im Parsing-Vorgang auszulösen.

Diese Seite erklärt, was Verarbeitungsanweisungen sind, beschreibt die Syntax und Parameter der Funktion, enthält ein vollständiges, ausführbares Beispiel, die Handler-Signatur, häufige Stolperfallen sowie die modernen Alternativen, die heute empfohlen werden.

⚠️ Deprecation-Hinweis: Die xml-Erweiterung wurde in PHP 8.0 als veraltet markiert und in PHP 8.2 vollständig entfernt. Diese Funktion ist nur in PHP 7.4 und früher verfügbar. Für moderne Projekte sollten Sie stattdessen XMLReader oder DOMDocument verwenden.

Was ist eine Verarbeitungsanweisung?

Eine Verarbeitungsanweisung (PI) ist ein spezieller XML-Knoten, der anwendungsspezifische Anweisungen an die Software übermittelt, die das Dokument verarbeitet. Es handelt sich nicht um Element-Inhalt – sie befindet sich zwischen dem Markup. Eine PI besteht aus zwei Teilen: einem Ziel (der Name direkt nach <?) und Daten (alles bis zum schließenden ?>):

<?target data ?>

Beispielsweise hat <?php-cache ttl="60" ?> das Ziel php-cache und die Daten ttl="60". Die XML-Deklaration <?xml version="1.0"?> sieht wie eine PI aus, wird jedoch besonders behandelt und löst diesen Handler nicht aus.

Syntax

Die Syntax der Funktion xml_set_processing_instruction_handler() lautet wie folgt:

xml_set_processing_instruction_handler($parser, $handler)

Dabei ist $parser die XML-Parser-Ressource, die von xml_parser_create() zurückgegeben wird, und $handler ist ein Callable oder ein String mit dem Namen der benutzerdefinierten Funktion, die Verarbeitungsanweisungen verarbeiten soll. Übergeben Sie einen leeren String ("") um einen zuvor registrierten Handler zu entfernen.

Parameter

Rückgabewert

Gibt true bei Erfolg zurück oder false, wenn $parser kein gültiger XML-Parser ist.

Die Handler-Signatur

Ihr Handler wird mit genau drei Argumenten aufgerufen:

function handler($parser, string $target, string $data): void

• $parser — der Parser, der den Callback ausgelöst hat.
• $target — das PI-Ziel (der Name direkt nach <?).
• $data — der Rest der PI als roher String. Sie sind selbst dafür verantwortlich, ihn zu parsen; der XML-Parser teilt ihn nicht in Attribute auf.

Verwendungsbeispiele

Schauen wir uns ein praktisches Beispiel für die Verwendung von xml_set_processing_instruction_handler() in PHP an.

Beispiel: Setzen einer Verarbeitungsanweisungs-Handler-Funktion

Angenommen, Sie haben einen XML-String, der Verarbeitungsanweisungen enthält. Sie können die Funktion xml_parser_create() verwenden, um einen neuen XML-Parser zu erstellen, und dann mithilfe von xml_set_processing_instruction_handler() eine Verarbeitungsanweisungs-Handler-Funktion festlegen:

function handle_processing_instruction($parser, $target, $data) {
    echo "Processing instruction found: $target - $data\n";
}

$xml_parser = xml_parser_create();
xml_set_processing_instruction_handler($xml_parser, "handle_processing_instruction");

$xml_data = '<?xml version="1.0"?><root><?PI target data?></root>';
if (!xml_parse($xml_parser, $xml_data)) {
    echo "XML parse error: " . xml_error_string(xml_get_error_code($xml_parser));
}

xml_parser_free($xml_parser);

Dieser Code erstellt einen neuen Parser mit xml_parser_create(). Anschließend wird eine benutzerdefinierte Funktion zum Verarbeiten von Verarbeitungsanweisungen gesetzt. Die Funktion xml_parse() verarbeitet den XML-String und löst den Handler aus, wenn eine Verarbeitungsanweisung gefunden wird. Der Rückgabewert wird geprüft, damit xml_error_string() etwaige Parsing-Fehler melden kann. Schließlich gibt xml_parser_free() die Parser-Ressource nach der Verwendung frei.

Unter PHP 7.4 gibt das Programm aus:

Processing instruction found: PI - target data

Beispiel: PI-Daten in Optionen parsen

PI-Daten kommen als ein einzelner roher String an, sodass jede darin enthaltene Struktur von Ihnen geparst werden muss. Ein gängiges Muster ist die Behandlung der Daten als key="value"-Paare:

function pi_handler($parser, $target, $data) {
    // Pull out key="value" pairs from the PI data
    preg_match_all('/(\w+)="([^"]*)"/', $data, $pairs, PREG_SET_ORDER);
    $options = [];
    foreach ($pairs as $pair) {
        $options[$pair[1]] = $pair[2];
    }
    echo "Target: $target\n";
    print_r($options);
}

$parser = xml_parser_create();
xml_set_processing_instruction_handler($parser, "pi_handler");
xml_parse($parser, '<root><?cache ttl="60" scope="page"?></root>');
xml_parser_free($parser);

Unter PHP 7.4 gibt dies aus:

Target: cache
Array
(
    [ttl] => 60
    [scope] => page
)

Verwandte Handler

xml_set_processing_instruction_handler() ist einer aus einer Familie von SAX-Handler-Settern. In der Regel registrieren Sie mehrere davon gemeinsam auf demselben Parser:

• xml_set_element_handler() — Start- und End-Tags.
• xml_set_character_data_handler() — Text zwischen Tags.
• xml_set_default_handler() — alles, was kein anderer Handler erfasst.
• xml_set_object() — Handler an Objektmethoden statt an einfache Funktionen weiterleiten.

Häufige Stolperfallen

• Die XML-Deklaration ist hier keine PI. <?xml ... ?> wird vom Parser verarbeitet und erreicht Ihren Handler nie.
• Daten sind ungeparst. $data ist ein einzelner String. Der Parser zerlegt key="value"-Inhalte nicht in Attribute für Sie – das müssen Sie selbst erledigen.
• Handler vor dem Parsen setzen. Registrieren Sie den Handler bevor Sie xml_parse() aufrufen, sonst werden frühe Anweisungen übersehen.
• PHP 8.2+ hat keine xml-Erweiterung mehr. Alle xml_*-Funktionen sind entfernt; die Beispiele auf dieser Seite laufen nur unter PHP 7.4 oder früher.

Fazit

In diesem Artikel haben wir PHPs Funktion xml_set_processing_instruction_handler() besprochen und erläutert, wie sie verwendet werden kann, um einen Verarbeitungsanweisungs-Handler für einen XML-Parser in der veralteten xml-Erweiterung zu setzen. Wir haben die Syntax erklärt und ein praktisches Beispiel bereitgestellt. Da die xml-Erweiterung in PHP 8.2 entfernt wurde, sollten moderne Anwendungen XMLReader oder DOMDocument für die XML-Verarbeitung bevorzugen. Für Legacy-Codebases, die auf PHP 7.4 oder früher laufen, bleibt diese Funktion eine zuverlässige Möglichkeit, Verarbeitungsanweisungen beim SAX-Parsing zu behandeln.

Übungen