xml_get_current_byte_index — Funktion · PHP-Referenz

Signatur

xml_get_current_byte_index(XMLParser $parser): int

Beschreibung

xml_get_current_byte_index() liefert die aktuelle Byte-Position innerhalb des XML-Dokuments, das vom angegebenen Parser verarbeitet wird. Dabei handelt es sich um den absoluten Offset in Bytes ab dem Anfang des Dokuments, nicht um eine Zeichen- oder Zeilen-Position.

Diese Funktion wird typischerweise innerhalb von Fehler-Callbacks oder Handler-Funktionen aufgerufen, die über xml_set_error_handler() oder andere xml_set_*_handler()-Funktionen registriert wurden. So lässt sich präzise bestimmen, an welcher Stelle im Rohdatenstrom ein Fehler oder ein bestimmtes Ereignis aufgetreten ist.

Besonders nützlich ist der Byte-Index in Kombination mit xml_get_current_line_number() und xml_get_current_column_number(), um aussagekräftige Fehlermeldungen zu erzeugen oder fehlerhafte Stellen in großen XML-Dokumenten schnell zu lokalisieren. Bei mehrbyte-kodierten Dokumenten (z. B. UTF-8) entspricht der Byte-Index nicht zwingend der Zeichen-Position.

Hinweis: Ab PHP 8.0.0 erwartet die Funktion ein XMLParser-Objekt statt einer Resource, da der interne Typ geändert wurde.

Parameter

Name	Typ	Default	Beschreibung
$parser Pflicht	XMLParser		Eine gültige `XMLParser`-Instanz (vor PHP 8.0 eine XML-Parser-Resource), die mit `xml_parser_create()` oder `xml_parser_create_ns()` erzeugt wurde.

Rückgabewert

Typ

int

Beschreibung

Gibt den aktuellen Byte-Offset (0-basiert) im verarbeiteten XML-Datenstrom zurück. Dieser Wert entspricht der Anzahl der Bytes ab dem Dokumentanfang bis zur aktuellen Parser-Position.

Beispiele

Byte-Index bei einem XML-Fehler ausgeben

<?php
$xml = '<?xml version="1.0"?><root><item>Text</item><broken></root>';

$parser = xml_parser_create();

function handleError(int $errno, string $errstr): void {
    // Wird hier nicht direkt verwendet, Fehler wird unten abgefangen
}

if (!xml_parse($parser, $xml, true)) {
    $errorCode   = xml_get_error_code($parser);
    $errorString = xml_error_string($errorCode);
    $byteIndex   = xml_get_current_byte_index($parser);
    $line        = xml_get_current_line_number($parser);
    $column      = xml_get_current_column_number($parser);

    echo "XML-Fehler: {$errorString}" . PHP_EOL;
    echo "Zeile: {$line}, Spalte: {$column}, Byte-Index: {$byteIndex}" . PHP_EOL;
}

xml_parser_free($parser);

XML-Fehler: Mismatched tag Zeile: 1, Spalte: 58, Byte-Index: 57

Byte-Index in einem Element-Handler nutzen

<?php
$xml = '<?xml version="1.0"?><catalog><book id="1"><title>PHP 8</title></book></catalog>';

$parser = xml_parser_create();

function startElement(XMLParser $parser, string $name, array $attrs): void {
    $byteIndex = xml_get_current_byte_index($parser);
    echo "Element &lt;{$name}&gt; beginnt bei Byte-Index: {$byteIndex}" . PHP_EOL;
}

xml_set_element_handler($parser, 'startElement', null);
xml_parse($parser, $xml, true);
xml_parser_free($parser);

Element <CATALOG> beginnt bei Byte-Index: 21 Element <BOOK> beginnt bei Byte-Index: 30 Element <TITLE> beginnt bei Byte-Index: 41

// Wichtig · Fallstricke

Mehrbyte-Kodierungen: Bei UTF-8-kodierten Dokumenten kann der Byte-Index von der Zeichen-Position abweichen, da ein Zeichen mehrere Bytes belegen kann. Wer genaue Zeichenpositionen benötigt, muss die Byte-Sequenz eigenständig analysieren.

PHP 8.0: Ab PHP 8.0.0 wurde die interne XML-Parser-Resource durch das XMLParser-Objekt ersetzt. Älterer Code, der eine Resource erwartet oder übergibt, muss angepasst werden.

Der zurückgegebene Wert ist stets 0-basiert; das erste Byte des Dokuments hat den Index 0.

Siehe auch

xml_get_current_line_number xml_get_current_column_number xml_get_error_code xml_error_string xml_parser_create xml_parse