Signatur
Beschreibung
UConverter ist eine PHP-Klasse aus der intl-Erweiterung, die auf der ICU-Bibliothek (International Components for Unicode) basiert und eine leistungsfähige Möglichkeit bietet, Zeichenketten zwischen beliebigen, von ICU unterstützten Zeichenkodierungen zu konvertieren. Typische Anwendungsfälle sind die Umwandlung von Texten zwischen UTF-8, ISO-8859-1, Windows-1252, Shift-JIS und hunderten weiterer Kodierungen.
UConverter bietet gegenüber einfacheren Funktionen wie mb_convert_encoding() oder iconv() erweiterte Kontrolle: Über die Methoden setSourceEncoding() und setDestinationEncoding() lassen sich Quell- und Zielkodierung separat festlegen. Zusätzlich können Fehler beim Kodierungsvorgang (z. B. nicht darstellbare Zeichen) über Callback-Methoden individuell behandelt werden, indem man UConverter ableitet und toUCallback() bzw. fromUCallback() überschreibt.
Die statische Methode UConverter::convert() ermöglicht eine schnelle Einmal-Konvertierung ohne Objektinstanziierung. Für wiederholte Konvertierungen ist die Nutzung einer Objektinstanz effizienter, da die Kodierungsobjekte nur einmal initialisiert werden.
Die Liste aller unterstützten Kodierungsnamen kann über UConverter::getAvailable() abgerufen werden. Über UConverter::getAliases() lassen sich alternative Namen (Aliases) für eine bestimmte Kodierung ermitteln.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $destination_encoding | string|null | "utf-8" | Name der Zielkodierung, z. B. "UTF-8" oder "ISO-8859-1". Wird null übergeben, wird UTF-8 verwendet. |
| $source_encoding | string|null | "utf-8" | Name der Quellkodierung, z. B. "Windows-1252" oder "Shift_JIS". Wird null übergeben, wird UTF-8 verwendet. |
Beispiele
Einfache Konvertierung von ISO-8859-1 nach UTF-8
<?php
// Setzt die intl-Erweiterung voraus
$converter = new UConverter('UTF-8', 'ISO-8859-1');
// ISO-8859-1 kodierter String mit deutschem Umlaut
$iso = "\xE4\xF6\xFC"; // entspricht 'äöü' in ISO-8859-1
$utf8 = $converter->convert($iso);
echo $utf8; // Ausgabe: äöü
echo strlen($utf8) . PHP_EOL; // Byte-Länge in UTF-8 (z. B. 6)
echo mb_strlen($utf8) . PHP_EOL; // Zeichenanzahl: 3Statische Schnell-Konvertierung und verfügbare Kodierungen
<?php
// Statische Methode: kein Objekt nötig
$utf8String = UConverter::transcode(
"\xE4\xF6\xFC",
'UTF-8',
'ISO-8859-1'
);
echo $utf8String . PHP_EOL; // äöü
// Alle verfügbaren Kodierungen auflisten
$available = UConverter::getAvailable();
echo count($available) . ' Kodierungen verfügbar.' . PHP_EOL;
// Aliases für UTF-8 ermitteln
$aliases = UConverter::getAliases('UTF-8');
print_r($aliases);Eigener Fehler-Callback für nicht konvertierbare Zeichen
<?php
class MyConverter extends UConverter
{
// Wird aufgerufen, wenn ein Zeichen nicht aus Unicode konvertiert werden kann
public function fromUCallback(int $reason, array $source, int $codePoint, int &$error): mixed
{
// Ersetze nicht darstellbare Zeichen durch '?'
$error = UConverter::REASON_SUBSTITUTE;
return '?';
}
}
$conv = new MyConverter('ASCII', 'UTF-8');
// Das Emoji U+1F600 ist in ASCII nicht darstellbar
$result = $conv->convert("Hallo \u{1F600} Welt");
echo $result . PHP_EOL; // Ausgabe: Hallo ? Welt// Wichtig · Fallstricke
Voraussetzung: Die PHP-Erweiterung intl muss aktiviert sein (extension=intl in der php.ini). Die verfügbaren Kodierungen hängen von der installierten ICU-Version ab.
Namensgebung: ICU-Kodierungsnamen unterscheiden sich teilweise von jenen, die mb_convert_encoding() oder iconv() erwarten. Nutze UConverter::getAvailable() und UConverter::getAliases(), um gültige Namen zu ermitteln.
Fehlerbehandlung: Bei ungültigem Kodierungsnamen wird im Konstruktor eine IntlException geworfen (ab PHP 8.0) bzw. ein Fehler gesetzt. Prüfe daher stets den Rückgabewert oder fange Ausnahmen ab.
Performance: Für massenhafte Konvertierungen ist es effizienter, eine UConverter-Instanz einmalig zu erstellen und wiederzuverwenden, anstatt für jede Konvertierung UConverter::transcode() aufzurufen.