numfmt_format — Funktion · PHP-Referenz

Signatur

numfmt_format(NumberFormatter $formatter, int|float $num, int $type = NumberFormatter::TYPE_DEFAULT): string|false

Beschreibung

numfmt_format() ist die prozedurale Variante von NumberFormatter::format() und formatiert eine Ganzzahl oder Gleitkommazahl entsprechend der im Formatter definierten Locale-Regeln. Damit lassen sich Zahlen z. B. mit länderspezifischen Tausendertrennzeichen, Dezimalzeichen und Währungssymbolen darstellen.

Der optionale Parameter $type bestimmt, wie die Eingabezahl intern interpretiert wird (z. B. als Integer, Double oder Währungsbetrag). Standardmäßig wird der Typ automatisch aus dem übergebenen PHP-Wert abgeleitet. Die möglichen Konstanten sind in NumberFormatter::TYPE_* definiert.

Die Funktion eignet sich besonders dann, wenn Zahlen für die Darstellung in Benutzeroberflächen aufbereitet werden sollen – etwa beim Anzeigen von Preisen, Prozentwerten oder großen statistischen Werten in verschiedenen Sprachen und Regionen. Sie arbeitet dabei korrekt mit Unicode und internationalen Schreibweisen.

Schlägt die Formatierung fehl, gibt die Funktion false zurück; der genaue Fehler lässt sich mit numfmt_get_error_code() und numfmt_get_error_message() abfragen.

Parameter

Name	Typ	Default	Beschreibung
$formatter Pflicht	NumberFormatter		Ein `NumberFormatter`-Objekt, das zuvor mit `numfmt_create()` oder `new NumberFormatter()` erstellt wurde und die Locale sowie den Formatierungsstil enthält.
$num Pflicht	int\|float		Die zu formatierende Zahl. Kann eine Ganzzahl oder eine Gleitkommazahl sein.
$type	int	NumberFormatter::TYPE_DEFAULT	Legt fest, wie `$num` interpretiert werden soll. Gültige Werte sind `NumberFormatter::TYPE_DEFAULT`, `NumberFormatter::TYPE_INT32`, `NumberFormatter::TYPE_INT64`, `NumberFormatter::TYPE_DOUBLE` und `NumberFormatter::TYPE_CURRENCY`.

Rückgabewert

Typ

string|false

Beschreibung

Gibt die formatierte Zahl als Zeichenkette zurück. Im Fehlerfall wird false zurückgegeben; Fehlerdetails können mit numfmt_get_error_code() und numfmt_get_error_message() abgefragt werden.

Beispiele

Zahl mit deutschem Locale formatieren

<?php
$fmt = numfmt_create('de_DE', NumberFormatter::DECIMAL);

$zahl = 1234567.89;
$ausgabe = numfmt_format($fmt, $zahl);

echo $ausgabe;
// Ausgabe: 1.234.567,89

1.234.567,89

Währungsformatierung für verschiedene Locales

<?php
$locales = ['de_DE', 'en_US', 'fr_FR', 'ja_JP'];
$betrag = 9999.99;

foreach ($locales as $locale) {
    $fmt = numfmt_create($locale, NumberFormatter::CURRENCY);
    // Währung für Decimal-Formatter explizit setzen
    $fmt2 = numfmt_create($locale, NumberFormatter::DECIMAL);
    $ausgabe = numfmt_format($fmt2, $betrag);
    echo $locale . ': ' . $ausgabe . PHP_EOL;
}
// de_DE: 9.999,99
// en_US: 9,999.99
// fr_FR: 9 999,99
// ja_JP: 9,999.99

de_DE: 9.999,99 en_US: 9,999.99 fr_FR: 9 999,99 ja_JP: 9,999.99

Ganzzahl explizit als TYPE_INT32 formatieren

<?php
$fmt = numfmt_create('en_US', NumberFormatter::DECIMAL);

$wert = 42000;
$ausgabe = numfmt_format($fmt, $wert, NumberFormatter::TYPE_INT32);

echo $ausgabe;
// Ausgabe: 42,000

42,000

// Wichtig · Fallstricke

Fehlerbehandlung: Da die Funktion im Fehlerfall false zurückgibt, sollte der Rückgabewert mit === false geprüft werden, da eine formatierte "0" sonst fälschlicherweise als Fehler interpretiert werden könnte.

Erweiterung: Die Funktion erfordert die PHP-Erweiterung intl, die standardmäßig nicht immer aktiviert ist. Stellen Sie sicher, dass extension=intl in der php.ini eingetragen ist.

TYPE_CURRENCY: Für die Währungsformatierung empfiehlt sich die Methode NumberFormatter::formatCurrency() bzw. numfmt_format_currency(), da dort die Währungseinheit explizit angegeben werden kann.

Siehe auch

NumberFormatter::format numfmt_create numfmt_parse numfmt_format_currency numfmt_get_error_code numfmt_get_error_message number_format