Signatur
Beschreibung
mb_encode_numericentity() konvertiert Zeichen in einem Multibyte-String anhand einer benutzerdefinierten Mapping-Tabelle in dezimale oder hexadezimale numerische HTML-Entities. Dies ist besonders nützlich, wenn HTML-Seiten mit einem beschränkten Zeichensatz (z. B. ISO-8859-1 oder ASCII) ausgegeben werden, aber Sonderzeichen oder Nicht-ASCII-Zeichen wie japanische Kana oder chinesische Schriftzeichen korrekt dargestellt werden sollen.
Die Mapping-Tabelle ($map) ist ein flaches Array, das Gruppen von je vier Ganzzahlen enthält: Startwert des Unicode-Codepoint-Bereichs, Endwert des Bereichs, Offset sowie ein Masken-Flag. Für jeden Codepoint im angegebenen Bereich wird das Zeichen durch die entsprechende numerische Entity ersetzt. Durch den Offset lassen sich Verschiebungen innerhalb des Bereichs ausdrücken.
Das optionale Flag 0x1000000 im vierten Element jeder Gruppe bewirkt, dass die Entity hexadezimal kodiert wird (z. B. あ statt あ). Ohne dieses Flag wird dezimale Kodierung verwendet.
Die Funktion ist das Gegenstück zu mb_decode_numericentity() und wird typischerweise bei der Ausgabe von Multibyte-Inhalten in HTML-Dokumenten mit beschränktem Zeichensatz eingesetzt.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $string Pflicht | string | Der zu kodierende Eingabe-String. Multibyte-Zeichen werden entsprechend der angegebenen oder internen Kodierung interpretiert. | |
| $map Pflicht | array | Flaches Array mit je vier Ganzzahlen pro Gruppe: [start, end, offset, mask]. start und end definieren den Unicode-Codepoint-Bereich (inklusive), offset den Versatz, der auf den Codepoint addiert wird, und mask steuert die Ausgabe (z. B. 0 für dezimal, 0x1000000 für hexadezimal). |
|
| $encoding | ?string | null | Die Zeichenkodierung des Eingabe-Strings (z. B. 'UTF-8', 'EUC-JP'). Bei null wird die interne Kodierung verwendet, die mit mb_internal_encoding() gesetzt wurde. |
Rückgabewert
Beispiele
Japanische Zeichen in dezimale HTML-Entities umwandeln
<?php
// UTF-8-String mit japanischem Zeichen "あ" (U+3042)
$string = 'Hello あ World';
// Bereich U+3000–U+9FFF (CJK-Zeichen) in dezimale Entities kodieren
$map = [
0x0000, 0xFFFF, 0, 0 // Gesamter BMP-Bereich
];
$encoded = mb_encode_numericentity($string, $map, 'UTF-8');
echo $encoded;
// Ausgabe: Hello あ WorldNur bestimmte Zeichenbereiche hexadezimal kodieren
<?php
// Nur japanische Hiragana (U+3041–U+3096) hexadezimal enkodieren
$string = 'Test: あいう';
// 0x1000000 als Mask aktiviert hexadezimale Ausgabe
$map = [
0x3041, 0x3096, 0, 0x1000000
];
$encoded = mb_encode_numericentity($string, $map, 'UTF-8');
echo $encoded;
// Ausgabe: Test: あいうHTML-sicherer Output bei beschränktem Charset
<?php
// Seite wird als ISO-8859-1 ausgeliefert, Inhalt enthält Unicode-Sonderzeichen
$userInput = 'Preis: 100 €';
// Euro-Zeichen U+20AC in Entity umwandeln
$map = [
0x0080, 0xFFFF, 0, 0
];
$safe = mb_encode_numericentity($userInput, $map, 'UTF-8');
echo $safe;
// Ausgabe: Preis: 100 €// Wichtig · Fallstricke
Mapping-Array-Struktur: Das $map-Array muss immer ein Vielfaches von 4 Elementen enthalten. Ein falsch aufgebautes Array kann zu unerwartetem Verhalten führen. Jede Gruppe von vier Zahlen repräsentiert exakt einen Bereich.
Offset-Parameter: Der offset-Wert (drittes Element jeder Gruppe) wird zum Codepoint addiert, bevor die Entity ausgegeben wird. In den meisten Anwendungsfällen wird dieser Wert auf 0 gesetzt.
Hexadezimale vs. dezimale Ausgabe: Das Flag 0x1000000 im vierten Element aktiviert hexadezimale Ausgabe (&#xHHHH;). Beide Formen sind in HTML vollständig äquivalent und werden von allen modernen Browsern korrekt interpretiert.
Keine XSS-Schutzfunktion: Diese Funktion ist kein Ersatz für htmlspecialchars() oder htmlentities(). Sie kodiert lediglich die Zeichen, die in den definierten Bereichen liegen – HTML-Sonderzeichen wie <, > oder & werden nicht automatisch gesichert.