Signatur
Beschreibung
msgfmt_format() ist die prozedurale Variante von MessageFormatter::format() und formatiert eine ICU-Nachricht, indem die Platzhalter im Muster durch die übergebenen Werte ersetzt werden. Das Muster kann Platzhalter in der Form {0}, {name} oder mit Formatierungstypen wie {0, number}, {1, date, short} oder {2, plural, ...} enthalten.
Die Funktion eignet sich besonders für die Internationalisierung (i18n) von Anwendungen, da sie abhängig vom Locale automatisch Zahlen, Daten, Uhrzeiten und Plural-Regeln korrekt formatiert. Dadurch wird eine saubere Trennung von Nachrichtenstruktur und konkreten Werten ermöglicht.
Die Platzhalterwerte werden als indiziertes oder assoziatives Array übergeben. Numerische Schlüssel entsprechen den positionellen Platzhaltern {0}, {1} etc., während bei benannten Platzhaltern String-Schlüssel im Array verwendet werden müssen.
Im Fehlerfall gibt die Funktion false zurück. Mit msgfmt_get_error_code() und msgfmt_get_error_message() lassen sich dann Details zum aufgetretenen Fehler ermitteln.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $formatter Pflicht | MessageFormatter | Ein zuvor mit msgfmt_create() oder new MessageFormatter() erzeugtes MessageFormatter-Objekt, das Locale und Muster bereits enthält. |
|
| $values Pflicht | array | Assoziatives oder indiziertes Array mit den Werten, die in die Platzhalter des Musters eingesetzt werden. Numerische Schlüssel entsprechen {0}, {1} usw.; String-Schlüssel werden für benannte Platzhalter wie {name} verwendet. |
Rückgabewert
false zurückgegeben.Beispiele
Einfache Nachricht mit Zahl und Datum formatieren
<?php
$fmt = msgfmt_create('de_DE', '{0} hat am {1, date, long} {2, number} Punkte erreicht.');
$result = msgfmt_format($fmt, ['Anna', mktime(0, 0, 0, 6, 15, 2024), 4200]);
echo $result;Pluralformen mit benannten Platzhaltern
<?php
$pattern = '{count, plural,
=0 {Keine Nachrichten}
one {Eine Nachricht}
other {# Nachrichten}
} vorhanden.';
$fmt = msgfmt_create('de_DE', $pattern);
foreach ([0, 1, 5] as $count) {
echo msgfmt_format($fmt, ['count' => $count]) . PHP_EOL;
}Fehlerbehandlung bei ungültigem Wert
<?php
$fmt = msgfmt_create('en_US', 'The value is {0, number}.');
$result = msgfmt_format($fmt, ['not-a-number']);
if ($result === false) {
echo 'Fehler: ' . msgfmt_get_error_message($fmt);
} else {
echo $result;
}// Wichtig · Fallstricke
Voraussetzung: Die intl-Extension muss aktiviert sein (extension=intl in der php.ini). Die ICU-Bibliotheksversion beeinflusst, welche Formate und Plural-Regeln unterstützt werden.
Locale-Abhängigkeit: Trennzeichen für Zahlen, Datumsformate und Pluralregeln werden vollständig durch das beim Erstellen des MessageFormatter-Objekts angegebene Locale gesteuert. Stelle sicher, dass das gewünschte Locale auf dem Server installiert ist.
Typsicherheit: Wenn das Muster einen numerischen Platzhalter ({0, number}) erwartet, muss der übergebene Wert numerisch sein, sonst schlägt die Formatierung fehl und gibt false zurück.