Signatur
Beschreibung
msgfmt_format_message() ist die prozedurale Variante von MessageFormatter::formatMessage() und erlaubt es, eine ICU-Nachrichtenzeichenkette in einem einzigen Aufruf mit konkreten Werten zu befüllen. Sie kombiniert intern das Anlegen eines MessageFormatter-Objekts, das Einsetzen der übergebenen Argumente und das Zurückgeben des fertig formatierten Strings.
Das Muster folgt der ICU MessageFormat-Syntax. Darin können Platzhalter wie {0}, {name}, Plural-Regeln ({count, plural, one{# Artikel} other{# Artikel}}), Select-Konstrukte und Datums-/Zahlenformatierungen verwendet werden. Die Locale steuert dabei sprachspezifische Regeln (z. B. Pluralformen).
Die Funktion eignet sich besonders gut für einmalige Formatierungsoperationen, wenn kein MessageFormatter-Objekt wiederverwendet werden soll. Für häufig wiederkehrende Formatierungen mit demselben Muster ist es performanter, ein Objekt einmal zu instanziieren und format() mehrfach aufzurufen.
Die Funktion benötigt die PHP-Erweiterung intl. Ist diese nicht installiert, steht sie nicht zur Verfügung.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $locale Pflicht | string | Die Locale, nach der die Nachricht formatiert werden soll, z. B. 'de_DE', 'en_US' oder 'fr_FR'. Sie beeinflusst Pluralformen, Zahlen- und Datumsformate. |
|
| $pattern Pflicht | string | Das ICU-MessageFormat-Muster mit Platzhaltern wie {0} oder {name}. Darf Plural-, Select- und Format-Konstrukte nach ICU-Syntax enthalten. |
|
| $values Pflicht | array | Ein indiziertes oder assoziatives Array mit den Werten, die in das Muster eingesetzt werden. Die Schlüssel müssen zu den Platzhaltern im Muster passen (numerisch oder benannt). |
Rückgabewert
false zurückgegeben. Fehlermeldungen lassen sich anschließend über intl_get_error_message() und intl_get_error_code() abrufen.Beispiele
Einfache Platzhalter mit numerischem Array
<?php
// Einfache Substitution mit nummerierten Platzhaltern
$locale = 'de_DE';
$pattern = 'Hallo, {0}! Du hast {1} neue Nachrichten.';
$values = ['Maria', 5];
$result = msgfmt_format_message($locale, $pattern, $values);
echo $result;
Plural-Regel für korrekte Grammatik
<?php
// Pluralformen abhängig von der Anzahl
$locale = 'de_DE';
$pattern = 'Du hast {count, plural,
=0 {keine Datei}
one {eine Datei}
other {# Dateien}
} heruntergeladen.';
foreach ([0, 1, 3] as $count) {
echo msgfmt_format_message($locale, $pattern, ['count' => $count]) . "\n";
}
Datumsformatierung mit ICU-Pattern
<?php
// Datum in der gewünschten Locale ausgeben
$locale = 'de_DE';
$pattern = 'Bestelldatum: {date, date, long}';
$values = ['date' => mktime(0, 0, 0, 6, 15, 2024)];
$result = msgfmt_format_message($locale, $pattern, $values);
echo $result;
// Wichtig · Fallstricke
Erweiterung: Die Funktion ist nur verfügbar, wenn die PHP-Erweiterung intl installiert und aktiviert ist. Ohne intl tritt ein fataler Fehler auf.
Fehlerbehandlung: Bei einem Fehler gibt die Funktion false zurück. Zusätzliche Informationen liefern intl_get_error_message() und intl_get_error_code(). Es werden keine PHP-Warnungen ausgelöst.
Performance: Für einmalige Formatierungen ist diese Funktion komfortabel. Bei häufiger Nutzung desselben Musters in einer Schleife empfiehlt sich die OO-Schreibweise: $fmt = new MessageFormatter($locale, $pattern) gefolgt von wiederholten $fmt->format($values)-Aufrufen.
Sicherheit: Muster sollten nicht direkt aus Nutzereingaben übernommen werden, da sie komplexe Verarbeitungslogik enthalten können. Validiere Locale-Strings, wenn sie aus externen Quellen stammen.