Signatur
Beschreibung
MessageFormatter ist eine PHP-Klasse aus der intl-Erweiterung, die auf der ICU MessageFormat-Syntax basiert. Sie ermöglicht es, lokalisierte Nachrichten zu erstellen, in denen Platzhalter für Variablen, Zahlen, Datumsangaben und Pluralformen definiert werden können – abhängig von der jeweiligen Locale (Spracheinstellung).
Die Klasse eignet sich besonders für Anwendungen, die mehrsprachige Ausgaben benötigen: Man definiert ein Muster (Pattern) wie '{name} hat {count, plural, one {# Nachricht} other {# Nachrichten}}' und übergibt zur Laufzeit die konkreten Werte. Die Formatierung – inklusive korrekter Pluralregeln – erfolgt automatisch gemäß der angegebenen Locale.
Im Vergleich zu einfachen sprintf-Lösungen unterstützt MessageFormatter komplexe Regeln wie Pluralformen (die je nach Sprache erheblich variieren), Auswahlmuster (select), Datumsformate (date, time) und Zahlenformate (number). Das macht ihn zur bevorzugten Lösung in professionellen Internationalisierungs-Szenarien (i18n).
Die Klasse kann sowohl objektorientiert als auch über statische Methoden und die prozedurale Hilfsfunktion msgfmt_create() verwendet werden. Voraussetzung ist die aktivierte intl-PHP-Erweiterung und eine ausreichend aktuelle ICU-Bibliothek.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $locale Pflicht | string | Die Locale, gemäß der die Nachricht formatiert werden soll, z. B. 'de_DE', 'en_US' oder 'fr_FR'. |
|
| $pattern Pflicht | string | Das ICU-MessageFormat-Muster mit Platzhaltern, z. B. '{name} hat {count, plural, one {# Datei} other {# Dateien}} gelöscht.' |
Rückgabewert
Beispiele
Einfache Variablen-Substitution
<?php
$fmt = new MessageFormatter('de_DE', 'Hallo, {name}! Du hast {count} neue Nachrichten.');
$result = $fmt->format(['name' => 'Anna', 'count' => 5]);
echo $result;Pluralformen je nach Locale
<?php
$pattern = '{count, plural, one {# Datei wurde} other {# Dateien wurden}} gelöscht.';
$fmtDe = new MessageFormatter('de_DE', $pattern);
echo $fmtDe->format(['count' => 1]) . PHP_EOL;
echo $fmtDe->format(['count' => 3]) . PHP_EOL;
$fmtEn = new MessageFormatter('en_US', $pattern);
echo $fmtEn->format(['count' => 1]) . PHP_EOL;
echo $fmtEn->format(['count' => 3]) . PHP_EOL;Statische Methode formatMessage()
<?php
$result = MessageFormatter::formatMessage(
'de_DE',
'Der Preis beträgt {preis, number, currency}.',
['preis' => 12.99]
);
echo $result;Datumsformatierung mit MessageFormatter
<?php
$fmt = new MessageFormatter('de_DE', 'Heute ist {datum, date, long}.');
$result = $fmt->format(['datum' => mktime(0, 0, 0, 6, 15, 2024)]);
echo $result;Fehlerbehandlung bei ungültigem Muster
<?php
$fmt = MessageFormatter::create('de_DE', '{name, ungueltigerTyp}');
if ($fmt === null) {
echo 'Formatter konnte nicht erstellt werden.';
} else {
$result = $fmt->format(['name' => 'Test']);
if ($result === false) {
echo 'Fehler: ' . $fmt->getErrorMessage() . ' (Code: ' . $fmt->getErrorCode() . ')';
} else {
echo $result;
}
}// Wichtig · Fallstricke
Voraussetzung: Die intl-PHP-Erweiterung muss aktiviert sein (extension=intl in der php.ini). Die verfügbaren Features hängen von der Version der installierten ICU-Bibliothek ab – ältere ICU-Versionen unterstützen möglicherweise nicht alle Pluralregeln oder Formatierungsoptionen.
Fehlerbehandlung: Im Fehlerfall geben format() und parse() false zurück. Über getErrorCode() und getErrorMessage() lassen sich Details zum Fehler ermitteln. Die statische Methode MessageFormatter::create() gibt null zurück, wenn der Formatter nicht erstellt werden konnte.
Indizierte vs. benannte Platzhalter: ICU MessageFormat unterstützt sowohl numerisch indizierte Platzhalter ({0}, {1}) als auch benannte ({name}). Beim Aufruf von format() muss das Array entsprechend numerisch oder assoziativ aufgebaut sein.
Performance: Für häufig verwendete Muster empfiehlt es sich, das MessageFormatter-Objekt einmalig zu erstellen und wiederzuverwenden, statt bei jedem Aufruf formatMessage() zu verwenden, da der Konstruktor das Pattern kompiliert.