xml_get_current_byte_index()

Die Funktion xml_get_current_byte_index() ist eine eingebaute PHP-Funktion, die zurückgibt, wie viele Bytes des XML-Dokuments der Parser bereits verarbeitet hat. Sie ist Teil der veralteten XML-Parser-Erweiterung, die Dokumente im Streaming-SAX-Stil analysiert: Anstatt das gesamte Dokument in einen Baum zu laden, löst sie Callbacks aus, während sie das Markup durchläuft. Diese Funktion teilt Ihnen mit, wo sich der Parser befindet, wenn einer dieser Callbacks ausgeführt wird.

Normalerweise wird sie innerhalb eines Handlers aufgerufen, der mit xml_set_element_handler() oder xml_set_character_data_handler() registriert wurde. Sie ist am nützlichsten, um den Parsing-Fortschritt bei einer großen Datei zu melden oder um zu ermitteln, wo im Quelltext ein bestimmtes Element oder ein bestimmter Inhalt aufgetreten ist – beispielsweise um eine Fehlermeldung zu erstellen, die auf einen Byte-Offset verweist.

Diese Seite behandelt die Syntax der Funktion, den Rückgabewert, zwei praktische Beispiele sowie mögliche Fallstricke.

Syntax

xml_get_current_byte_index(XMLParser $parser): int

Parameter

• $parser — das Parser-Handle, das von xml_parser_create() oder xml_parser_create_ns() zurückgegeben wird. Ab PHP 8.0 ist dies ein XMLParser-Objekt; in PHP 7.x ist es eine resource.

Rückgabewert

Gibt den Byte-Offset (eine nullbasierte Ganzzahl) der aktuellen Position des Parsers im Dokument zurück. Da Bytes und nicht Zeichen gezählt werden, meldet eine UTF-8-Datei mit Mehrbytezeichen einen größeren Index als ihre Zeichenanzahl. Wenn Sie stattdessen eine Zeile oder Spalte benötigen, verwenden Sie die Hilfsfunktionen xml_get_current_line_number() und xml_get_current_column_number().

Der Wert ist nur während des laufenden Parsings sinnvoll (d. h. innerhalb eines Handlers). Ein Aufruf vor dem Start von xml_parse() gibt 0 zurück.

Verwendungsbeispiele

Schauen wir uns einige praktische Beispiele für die Verwendung von xml_get_current_byte_index() in PHP an.

Beispiel 1: Abrufen des aktuellen Byte-Index eines XML-Parsers

Angenommen, Sie haben eine XML-Datei „data.xml", die Sie mit der XML-Parser-Erweiterung in PHP analysieren möchten. Sie können die Funktion xml_get_current_byte_index() innerhalb eines SAX-Element-Handlers verwenden, um den aktuellen Byte-Index beim Start eines Elements abzurufen:

Abrufen des aktuellen Byte-Index eines XML-Parsers in PHP

$parser = xml_parser_create();
xml_parser_set_option($parser, XML_OPTION_CASE_FOLDING, 0);

function start_handler($parser, $name, $attrs) {
    $byte_index = xml_get_current_byte_index($parser);
    echo "Element <$name> starts at byte index: $byte_index\n";
}

xml_set_element_handler($parser, "start_handler", null);

$xml_data = file_get_contents("data.xml");
xml_parse($parser, $xml_data, true);
xml_parser_free($parser);

Dieser Code erstellt einen XML-Parser mit xml_parser_create() und deaktiviert die Case-Folding-Option. Er definiert einen start_handler-Callback, der xml_get_current_byte_index() aufruft, um die aktuelle Position des Parsers zu ermitteln, sobald ein Element beginnt. Der Handler wird mit xml_set_element_handler() registriert, und xml_parse() verarbeitet die Datei. Abschließend wird der vom XML-Parser belegte Speicher mit xml_parser_free() freigegeben.

Beispiel 2: Verfolgen des Parsing-Fortschritts

Angenommen, Sie haben eine große XML-Datei und möchten während des Parsens einen Fortschrittsindikator anzeigen. Sie können die XML-Parser-Erweiterung mit einem Character-Data-Handler verwenden, um den Byte-Index zu verfolgen, während der Parser die Datei liest:

Verfolgen des Parsing-Fortschritts in PHP

$parser = xml_parser_create();
xml_parser_set_option($parser, XML_OPTION_CASE_FOLDING, 0);

$total_bytes = filesize("data.xml");
$last_reported = 0;

function progress_handler($parser, $data) {
    global $last_reported, $total_bytes;
    $current = xml_get_current_byte_index($parser);
    if ($current - $last_reported > 1024) { // Report every 1KB
        $progress = round(($current / $total_bytes) * 100);
        echo "Parsing progress: $progress%\n";
        $last_reported = $current;
    }
}

xml_set_character_data_handler($parser, "progress_handler");
xml_parse($parser, file_get_contents("data.xml"), true);
xml_parser_free($parser);

Dieser Code erstellt einen XML-Parser und berechnet die Gesamtgröße der Datei. Er definiert einen progress_handler-Callback, der den aktuellen Byte-Index mit der zuletzt gemeldeten Position vergleicht. Wurden mehr als 1 KB gelesen, wird der Parsing-Prozentsatz berechnet und ausgegeben. Der Handler wird mit xml_set_character_data_handler() registriert, und xml_parse() verarbeitet die Datei. Abschließend wird der vom XML-Parser belegte Speicher mit xml_parser_free() freigegeben.

Hinweise und Fallstricke

• Bytes, nicht Zeichen. Bei einem UTF-8-Dokument mit Mehrbytezeichen kann der zurückgegebene Offset größer sein als die Zeichenposition. Behandeln Sie ihn nicht als Zeichenanzahl.
• Innerhalb eines Handlers aufrufen. Der Byte-Index spiegelt nur innerhalb eines laufenden Callbacks eine tatsächliche Position wider. Außerhalb des Parsings wird 0 zurückgegeben.
• Der Offset kann leicht hinter dem Markup liegen. Je nach libexpat-Pufferung kann der gemeldete Index am Ende des Tokens stehen, das den Callback ausgelöst hat, und nicht genau an dessen Anfang. Verwenden Sie ihn für ungefähre Fortschrittsanzeigen und Positionsangaben, nicht für byteexaktes Slicing.
• Dies ist die veraltete SAX-API. Für den Großteil neuen Codes sind die baumbasierten Erweiterungen SimpleXML oder DOM einfacher zu verwenden. Setzen Sie die XML-Parser-Erweiterung ein, wenn Sie speziell Streaming für sehr große Dateien benötigen. Eine Übersicht zur Auswahl finden Sie unter PHP XML-Parser.

Fazit

In diesem Artikel haben wir die PHP-Funktion xml_get_current_byte_index() und ihre Verwendung zum Abrufen des aktuellen Byte-Index eines XML-Parsers beim SAX-Stil-Parsing besprochen. Wir haben erläutert, was die Funktion tut, ihre Syntax erklärt und Beispiele für den praktischen Einsatz gezeigt. Anhand dieser Beispiele können Sie die Position des Parsers problemlos verfolgen und in Ihren PHP-Anwendungen nutzen, um den Fortschritt zu überwachen oder bestimmte Elemente zu lokalisieren.

Übung