mb_substitute_character — Funktion · PHP-Referenz

Signatur

mb_substitute_character(string|int|null $substitute_character = null): string|int|bool

Beschreibung

mb_substitute_character() steuert, welches Zeichen die Multibyte-String-Funktionen (z. B. mb_convert_encoding()) anstelle eines ungültigen oder nicht darstellbaren Zeichens einfügen. Dies ist besonders relevant, wenn Texte zwischen Zeichenkodierungen konvertiert werden und bestimmte Zeichen in der Zielkodierung nicht vorhanden sind.

Wird die Funktion ohne Argument aufgerufen, gibt sie das aktuell gesetzte Ersatzzeichen zurück. Wird ein Argument übergeben, wird das Ersatzzeichen geändert und true bei Erfolg zurückgegeben. Das Argument kann ein Unicode-Codepunkt als Ganzzahl (z. B. 0x3013), eine Zeichenkette wie 'none' (kein Ersatz, Zeichen wird weggelassen) oder 'long' (hexadezimale Darstellung, z. B. U+XXXX) sein.

Die Einstellung wirkt sich global auf alle nachfolgenden Multibyte-Konvertierungsvorgänge aus. Gerade bei der Verarbeitung von Benutzereingaben oder beim Einlesen externer Dateien ist es wichtig, dieses Verhalten klar zu definieren, um unerwartete Zeichen oder Datenverluste zu vermeiden.

Ab PHP 8.0 ist auch null als Argument erlaubt und setzt das Ersatzzeichen auf den Standardwert zurück (Unicode-Ersatzzeichen U+FFFD, 0xFFFD).

Parameter

Name	Typ	Default	Beschreibung
$substitute_character	string\|int\|null	null	Das neue Ersatzzeichen. Mögliche Werte: `'none'` — Ungültige Zeichen werden stillschweigend weggelassen. `'long'` — Ungültige Zeichen werden als hexadezimale Zeichenkette dargestellt (z. B. `U+FFFE`). `'entity'` — Ungültige Zeichen werden als HTML-Entity dargestellt (z. B. ``), verfügbar ab PHP 5.4. Ein Integer-Codepunkt (z. B. `0xFFFD`) — Gibt den Unicode-Codepunkt des gewünschten Ersatzzeichens an. `null` (ab PHP 8.0) — Setzt auf den Standardwert zurück (`0xFFFD`).

Rückgabewert

Typ

string|int|bool

Beschreibung

Wird kein Argument übergeben, gibt die Funktion das aktuell gesetzte Ersatzzeichen zurück — entweder als Integer (Codepunkt) oder als String ('none', 'long', 'entity').
Wird ein gültiges Argument übergeben, gibt die Funktion true zurück.
Bei einem ungültigen Argument gibt die Funktion false zurück.

Beispiele

Aktuelles Ersatzzeichen abfragen

<?php
// Aktuellen Wert abfragen (Standard ist 0xFFFD = 65533)
$current = mb_substitute_character();
var_dump($current);
// Beispielausgabe: int(65533)

int(65533)

Ungültige Zeichen bei Konvertierung weglassen

<?php
// Ungültige Zeichen stillschweigend entfernen
mb_substitute_character('none');

// Ein String mit einem ungültigen UTF-8-Byte
$invalid = "Hallo " . chr(0x80) . " Welt";
$converted = mb_convert_encoding($invalid, 'UTF-8', 'UTF-8');
echo $converted;

Hallo Welt

Hexadezimale Darstellung für ungültige Zeichen

<?php
// Ungültige Zeichen als hexadezimale Notation darstellen
mb_substitute_character('long');

$invalid = "Test" . chr(0x80) . "Ende";
$result = mb_convert_encoding($invalid, 'UTF-8', 'UTF-8');
echo $result;

TestU+0080Ende

Eigenes Ersatzzeichen als Unicode-Codepunkt setzen

<?php
// Fragezeichen (U+003F) als Ersatzzeichen verwenden
mb_substitute_character(0x3F);

$invalid = "Hallo" . chr(0xFF) . "Welt";
$result = mb_convert_encoding($invalid, 'UTF-8', 'UTF-8');
echo $result;

Hallo?Welt

// Wichtig · Fallstricke

Globale Wirkung: Die Einstellung gilt prozessweit für alle nachfolgenden Multibyte-Konvertierungen. Bei wiederverwendbarem Code (z. B. Bibliotheken) empfiehlt es sich, den alten Wert zu sichern und nach der Operation wiederherzustellen.

Zeichenkodierungs-Sicherheit: Bei der Verarbeitung von Benutzereingaben sollte das Verhalten bei ungültigen Zeichen explizit definiert werden. Das Weglassen ('none') kann zu Datenverlust führen; eine hexadezimale Darstellung ('long') ist besser für Debugging geeignet.

PHP 8.0+: Der Übergabewert null setzt das Ersatzzeichen auf den Standardwert zurück. In älteren PHP-Versionen ist dies nicht möglich.

Siehe auch

mb_convert_encoding mb_detect_encoding mb_internal_encoding mb_convert_variables