Signatur
Beschreibung
mb_decode_numericentity() ist das Gegenstück zu mb_encode_numericentity(). Die Funktion durchsucht den übergebenen String nach numerischen HTML-Entities in dezimaler (&#NNN;) oder hexadezimaler Schreibweise (&#xHHH;) und ersetzt diejenigen Codepoints, die in der Mapping-Tabelle $map beschrieben sind, durch die entsprechenden Zeichen in der Ziel-Kodierung.
Die Mapping-Tabelle $map ist ein flaches Array aus Gruppen von vier Integer-Werten: [offset, length, destoffset, mask, ...]. Für jeden Entity-Codepoint cp prüft die Funktion: (cp - offset) & ~mask <= length. Trifft das zu, wird der Codepoint (cp - offset + destoffset) in das Ausgabezeichen umgewandelt. Für die meisten Anwendungen, bei denen man einfach alle Entities im Unicode-Bereich dekodieren möchte, genügt das Mapping [0x0, 0x10FFFF, 0, 0xFF].
Die Funktion ist besonders nützlich, wenn HTML-Daten aus externen Quellen empfangen werden, die Zeichen als numerische Entities kodiert haben (z. B. japanische oder chinesische Zeichen in alten E-Mail-Systemen oder XML-Feeds), und diese in einen nativen Multibyte-String überführt werden sollen.
Der optionale Parameter $encoding legt die Zeichenkodierung des Ausgabe-Strings fest. Wird er weggelassen oder auf null gesetzt, verwendet die Funktion die interne Encoding-Einstellung, die mit mb_internal_encoding() gesetzt wurde.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $string Pflicht | string | Der Eingabe-String, der numerische HTML-Entities enthält, die dekodiert werden sollen. | |
| $map Pflicht | array | Flaches Array aus Gruppen von je vier Integer-Werten (offset, length, destoffset, mask), das den Codepoint-Bereich definiert, der umgewandelt werden soll. Für vollständige Unicode-Dekodierung: [0x0, 0x10FFFF, 0, 0xFF]. |
|
| $encoding | string|null | null | Zeichenkodierung des Ausgabe-Strings, z. B. 'UTF-8' oder 'Shift_JIS'. Wird null übergeben, gilt die interne Kodierung (mb_internal_encoding()). |
Rückgabewert
Beispiele
Alle Unicode-Entities in UTF-8-Zeichen dekodieren
<?php
// Vollständiges Unicode-Mapping: alle Codepoints von U+0000 bis U+10FFFF
$map = [0x0, 0x10FFFF, 0, 0xFF];
$html = 'Hallo 世界! Добро пожаловать!';
$decoded = mb_decode_numericentity($html, $map, 'UTF-8');
echo $decoded;
// Ausgabe: Hallo 世界! Добро пожаловать!Nur Codepoints im Shift_JIS-Bereich dekodieren
<?php
// Nur Zeichen im Bereich U+0020 bis U+007E (ASCII druckbar) umwandeln
$map = [0x20, 0x5E, 0x20, 0xFF];
$input = 'ABC ☺'; // A, B, C und Smiley (U+263A)
$result = mb_decode_numericentity($input, $map, 'UTF-8');
echo $result;
// A, B, C werden dekodiert; ☺ liegt außerhalb des Bereichs und bleibt als EntityZusammenspiel mit mb_encode_numericentity (Round-Trip)
<?php
$original = 'こんにちは世界';
$map = [0x0, 0x10FFFF, 0, 0xFF];
// Kodieren
$encoded = mb_encode_numericentity($original, $map, 'UTF-8');
echo $encoded . "\n";
// こんにちは世界
// Dekodieren
$decoded = mb_decode_numericentity($encoded, $map, 'UTF-8');
echo $decoded . "\n";
// こんにちは世界
var_dump($original === $decoded); // bool(true)// Wichtig · Fallstricke
Mapping-Format: Das $map-Array muss immer ein Vielfaches von 4 Einträgen enthalten. Fehler in der Mapping-Tabelle (z. B. falsche Anzahl) können zu unerwartetem Verhalten führen.
Nur numerische Entities: Die Funktion dekodiert ausschließlich numerische HTML-Entities (&#NNN; und &#xHHH;). Benannte Entities wie & oder ü werden nicht umgewandelt — dafür ist html_entity_decode() zuständig.
Sicherheit: Beim Einlesen von Nutzerdaten, die anschließend als HTML ausgegeben werden, sollte der dekodierte String anschließend mit htmlspecialchars() gesichert werden, um XSS-Angriffe zu verhindern, da Entities-Kodierung allein keine Sicherheitsmaßnahme darstellt.