Signatur
Beschreibung
NumberFormatter ist Teil der intl-Erweiterung (ICU-basiert) und ermöglicht die Locale-abhängige Darstellung von Ganzzahlen, Dezimalzahlen, Währungen, Prozentwerten und wissenschaftlichen Notationen. Damit lassen sich Zahlen so ausgeben, wie der jeweilige Nutzer es erwartet – z. B. 1.234,56 € in Deutschland oder $1,234.56 in den USA.
Die Klasse wird mit einem Locale-String und einem Stilkonstanten wie NumberFormatter::DECIMAL oder NumberFormatter::CURRENCY instanziiert. Anschließend können über format() Zahlen formatiert und über parse() lokalisierte Zeichenketten wieder in numerische Werte umgewandelt werden.
Über setAttribute(), setTextAttribute() und setSymbol() lassen sich zahlreiche Detaileinstellungen wie die minimale Nachkommastellenanzahl, das Währungssymbol oder Gruppentrennzeichen individuell anpassen.
Die Klasse eignet sich ideal für Webanwendungen mit Mehrsprachigkeit, Buchhaltungssoftware, Reporting-Tools oder überall dort, wo Zahlen und Geldbeträge korrekt und nutzerfreundlich dargestellt werden müssen.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $locale Pflicht | string | Ein gültiger Locale-Bezeichner nach BCP 47, z. B. de_DE, en_US oder fr_FR. Bestimmt Trennzeichen, Währungssymbol und weitere Formatierungsregeln. |
|
| $style Pflicht | int | Eine der Stilkonstanten der Klasse, z. B. NumberFormatter::DECIMAL, NumberFormatter::CURRENCY, NumberFormatter::PERCENT, NumberFormatter::SCIENTIFIC oder NumberFormatter::SPELLOUT. |
|
| $pattern | string | Ein optionales ICU-Formatierungsmuster (z. B. #,##0.00 ¤¤), das den gewählten Stil überschreibt. Nur für Stile wie NumberFormatter::PATTERN_DECIMAL oder NumberFormatter::PATTERN_RULEBASED relevant. |
Rückgabewert
Beispiele
Dezimalzahl und Währung Locale-abhängig formatieren
<?php
// Dezimalzahl auf Deutsch formatieren
$formatterDE = new NumberFormatter('de_DE', NumberFormatter::DECIMAL);
echo $formatterDE->format(1234567.89); // 1.234.567,89
echo PHP_EOL;
// Währung auf Deutsch
$currencyDE = new NumberFormatter('de_DE', NumberFormatter::CURRENCY);
echo $currencyDE->formatCurrency(1234.56, 'EUR'); // 1.234,56 €
echo PHP_EOL;
// Währung auf Englisch (US)
$currencyUS = new NumberFormatter('en_US', NumberFormatter::CURRENCY);
echo $currencyUS->formatCurrency(1234.56, 'USD'); // $1,234.56Lokalisierten String zurück in Zahl parsen
<?php
// Deutschen Zahlenstring in Float umwandeln
$formatter = new NumberFormatter('de_DE', NumberFormatter::DECIMAL);
$value = $formatter->parse('1.234,56');
var_dump($value); // float(1234.56)
// Deutschen Währungsstring parsen
$currencyFormatter = new NumberFormatter('de_DE', NumberFormatter::CURRENCY);
$currency = '';
$amount = $currencyFormatter->parseCurrency('1.234,56 €', $currency);
var_dump($amount); // float(1234.56)
var_dump($currency); // string(3) "EUR"Prozentwert und Nachkommastellenanzahl anpassen
<?php
$formatter = new NumberFormatter('de_DE', NumberFormatter::PERCENT);
// Mindestens 2 und maximal 2 Nachkommastellen
$formatter->setAttribute(NumberFormatter::MIN_FRACTION_DIGITS, 2);
$formatter->setAttribute(NumberFormatter::MAX_FRACTION_DIGITS, 2);
echo $formatter->format(0.1756); // 17,56 %
echo PHP_EOL;
echo $formatter->format(0.5); // 50,00 %// Wichtig · Fallstricke
Voraussetzung: Die PHP-Erweiterung intl muss aktiviert sein (extension=intl in der php.ini). Fehlt die Erweiterung, führt die Instanziierung zu einem Fatal Error.
Fehlerbehandlung: Im Fehlerfall geben format() und parse() false zurück. Den letzten Fehlercode kann man mit NumberFormatter::getErrorCode() und die Fehlermeldung mit NumberFormatter::getErrorMessage() abrufen.
Locale-Verfügbarkeit: Nicht alle ICU-Locales sind auf jedem System verfügbar. Ein ungültiges oder fehlendes Locale kann zu unerwartetem Verhalten führen. Prüfe mit intl_is_failure() nach kritischen Operationen auf Fehler.
Performance: Das Erstellen eines NumberFormatter-Objekts ist verhältnismäßig teuer. In Schleifen oder häufig aufgerufenen Code-Stellen empfiehlt es sich, die Instanz zu cachen (z. B. als statische Variable oder im DI-Container).