numfmt_create — Funktion · PHP-Referenz

Signatur

numfmt_create(string $locale, int $style, string $pattern = ''): NumberFormatter|false

Beschreibung

numfmt_create() ist die prozedurale Variante von NumberFormatter::create() bzw. new NumberFormatter() und erzeugt eine Instanz des Zahlenformatters aus der ICU-Bibliothek. Sie wird verwendet, um Zahlen, Währungsbeträge, Prozentsätze und andere numerische Werte gemäß den Konventionen einer bestimmten Locale (z. B. de_DE, en_US) korrekt darzustellen.

Der Parameter $style bestimmt, wie die Zahl dargestellt werden soll. Typische Werte sind NumberFormatter::DECIMAL für Dezimalzahlen, NumberFormatter::CURRENCY für Währungsformatierung oder NumberFormatter::PERCENT für Prozentwerte. Alle verfügbaren Stile sind als Konstanten in der Klasse NumberFormatter definiert.

Optional kann ein CLDR- oder ICU-Muster als $pattern übergeben werden, wenn PATTERN_DECIMAL oder PATTERN_RULEBASED als Stil verwendet wird. Dies ermöglicht eine vollständig benutzerdefinierte Formatierung.

Im Gegensatz zu number_format() berücksichtigt numfmt_create() automatisch locale-spezifische Dezimal- und Tausendertrennzeichen, Währungssymbole und andere kulturelle Konventionen, was es zur bevorzugten Wahl für internationale Anwendungen macht.

Parameter

Name	Typ	Beschreibung
$locale Pflicht	string	Die Locale, für die der Formatter erstellt wird, z. B. `'de_DE'`, `'en_US'` oder `'fr_FR'`. Ein leerer String verwendet die Standard-Locale der Umgebung.
$style Pflicht	int	Der Formatierungsstil als eine der `NumberFormatter`-Konstanten, z. B. `NumberFormatter::DECIMAL`, `NumberFormatter::CURRENCY`, `NumberFormatter::PERCENT` oder `NumberFormatter::SPELLOUT`.
$pattern	string	Optionales ICU-Formatmuster, das verwendet wird, wenn der Stil `NumberFormatter::PATTERN_DECIMAL` oder `NumberFormatter::PATTERN_RULEBASED` ist. Wird bei anderen Stilen ignoriert.

Rückgabewert

Typ

NumberFormatter|false

Beschreibung

Gibt bei Erfolg ein NumberFormatter-Objekt zurück, das für die weitere Formatierung und das Parsen verwendet werden kann. Bei einem Fehler (z. B. ungültige Locale oder ungültiger Stil) wird false zurückgegeben.

Beispiele

Dezimalzahl nach deutschem Standard formatieren

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

if ($formatter !== false) {
    echo numfmt_format($formatter, 1234567.89);
} else {
    echo 'Formatter konnte nicht erstellt werden.';
}

1.234.567,89

Währungsbetrag für verschiedene Locales ausgeben

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

foreach ($locales as $locale) {
    $formatter = numfmt_create($locale, NumberFormatter::CURRENCY);
    if ($formatter !== false) {
        // EUR für DE und FR, USD für US, JPY für JP
        $waehrung = match ($locale) {
            'de_DE', 'fr_FR' => 'EUR',
            'en_US'          => 'USD',
            'ja_JP'          => 'JPY',
        };
        echo $locale . ': ' . numfmt_format_currency($formatter, $betrag, $waehrung) . PHP_EOL;
    }
}

de_DE: 12.345,67 € en_US: $12,345.67 fr_FR: 12 345,67 € ja_JP: ¥1,234,567

Prozentwert formatieren

<?php
$formatter = numfmt_create('de_DE', NumberFormatter::PERCENT);

if ($formatter !== false) {
    // 0.753 entspricht 75,3 %
    echo numfmt_format($formatter, 0.753);
}

75 %

// Wichtig · Fallstricke

Erweiterung erforderlich: numfmt_create() benötigt die PHP-Erweiterung intl, die auf dem System aktiviert sein muss. Ohne diese Erweiterung ist die Funktion nicht verfügbar.

Rückgabewert prüfen: Der Rückgabewert sollte immer auf false geprüft werden, da ungültige Locales oder Stile zu einem Fehler führen können. Mit numfmt_get_error_code() und numfmt_get_error_message() lassen sich Fehlerdetails ermitteln.

OOP-Äquivalent: Die objektorientierte Schreibweise new NumberFormatter($locale, $style) ist gleichwertig und in modernem Code oft bevorzugt.

Siehe auch

NumberFormatter numfmt_format numfmt_format_currency numfmt_parse numfmt_get_error_code number_format