xml_set_character_data_handler — Funktion · PHP-Referenz

Signatur

xml_set_character_data_handler(XMLParser $parser, callable $handler): bool

Beschreibung

xml_set_character_data_handler() legt fest, welche Funktion aufgerufen wird, wenn der expat-basierte XML-Parser auf Zeichendaten (Character Data) trifft – also auf den Textinhalt zwischen öffnenden und schließenden XML-Tags. Der Handler wird für jeden zusammenhängenden Textblock einmal aufgerufen, kann aber bei größeren Dokumenten auch mehrfach für dasselbe Element aufgerufen werden.

Der registrierte Handler muss zwei Parameter akzeptieren: das Parser-Handle (XMLParser) und einen String mit den tatsächlichen Zeichendaten. Typischer Einsatz ist das Einlesen von Textwerten aus XML-Elementen wie <title>PHP ist toll</title>.

Die Funktion arbeitet zusammen mit anderen Handler-Funktionen wie xml_set_element_handler() für Start- und End-Tags. Für vollständige XML-Verarbeitung empfiehlt sich der kombinierte Einsatz all dieser Handler, um sowohl Struktur als auch Inhalt des Dokuments korrekt zu erfassen.

Alternativ kann statt eines einfachen Funktionsnamens auch ein Array [$objekt, 'methodenname'] übergeben werden, um eine Methode eines Objekts als Handler zu nutzen.

Parameter

Name	Typ	Default	Beschreibung
$parser Pflicht	XMLParser		Das XML-Parser-Handle, das zuvor mit `xml_parser_create()` oder `xml_parser_create_ns()` erstellt wurde.
$handler Pflicht	callable		Die Callback-Funktion, die bei Zeichendaten aufgerufen wird. Sie muss die Signatur `handler(XMLParser $parser, string $data): void` erfüllen. `$data` enthält die erkannten Zeichendaten. Um einen zuvor gesetzten Handler zu entfernen, kann ein leerer String oder `false` übergeben werden.

Rückgabewert

Typ

bool

Beschreibung

Gibt true zurück, wenn der Handler erfolgreich gesetzt wurde, andernfalls false.

Beispiele

Einfaches Auslesen von Textinhalten aus XML

<?php
$xml = '<?xml version="1.0"?>
<buecher>
  <buch>
    <titel>PHP 8 Handbuch</titel>
    <autor>Max Mustermann</autor>
  </buch>
</buecher>';

$aktuellesElement = '';
$daten = [];

$parser = xml_parser_create('UTF-8');

xml_set_element_handler(
    $parser,
    function (XMLParser $parser, string $name, array $attribs) use (&$aktuellesElement) {
        $aktuellesElement = strtolower($name);
    },
    function (XMLParser $parser, string $name) use (&$aktuellesElement) {
        $aktuellesElement = '';
    }
);

xml_set_character_data_handler(
    $parser,
    function (XMLParser $parser, string $data) use (&$aktuellesElement, &$daten) {
        $text = trim($data);
        if ($text !== '' && in_array($aktuellesElement, ['titel', 'autor'])) {
            $daten[$aktuellesElement][] = $text;
        }
    }
);

xml_parse($parser, $xml, true);
xml_parser_free($parser);

print_r($daten);

Array ( [titel] => Array ( [0] => PHP 8 Handbuch ) [autor] => Array ( [0] => Max Mustermann ) )

Handler als Methode eines Objekts

<?php
class XmlLeser
{
    public array $texte = [];
    private string $aktuellesTag = '';

    public function startHandler(XMLParser $parser, string $name, array $attribs): void
    {
        $this->aktuellesTag = strtolower($name);
    }

    public function endHandler(XMLParser $parser, string $name): void
    {
        $this->aktuellesTag = '';
    }

    public function zeichenHandler(XMLParser $parser, string $data): void
    {
        $text = trim($data);
        if ($text !== '') {
            $this->texte[$this->aktuellesTag][] = $text;
        }
    }
}

$leser  = new XmlLeser();
$parser = xml_parser_create('UTF-8');

xml_set_object($parser, $leser);
xml_set_element_handler($parser, 'startHandler', 'endHandler');
xml_set_character_data_handler($parser, 'zeichenHandler');

$xml = '<?xml version="1.0"?><news><item>Breaking: PHP 9 erschienen</item></news>';
xml_parse($parser, $xml, true);
xml_parser_free($parser);

print_r($leser->texte);

Array ( [item] => Array ( [0] => Breaking: PHP 9 erschienen ) )

// Wichtig · Fallstricke

Wichtig: Der Character-Data-Handler kann für einen einzelnen Textknoten mehrfach aufgerufen werden, da der Parser große Texte in mehrere Blöcke aufteilen kann. Textwerte sollten daher akkumuliert und nicht einfach überschrieben werden. Erst beim Aufruf des End-Tag-Handlers ist sicher, dass alle Zeichendaten eines Elements vollständig vorliegen.

Whitespace (Leerzeichen, Zeilenumbrüche) zwischen Tags wird ebenfalls als Zeichendaten gemeldet. Ein trim() oder eine Leerzeichenprüfung im Handler ist daher ratsam, um unerwünschte Leereinträge zu vermeiden.

Seit PHP 8.0 ist der erste Parameter vom Typ XMLParser (Objekt), davor war es eine resource.

Siehe auch

xml_parser_create xml_set_element_handler xml_set_object xml_parse xml_parser_free xml_set_processing_instruction_handler