Signatur
Beschreibung
numfmt_format_currency() ist die prozedurale Variante der Methode NumberFormatter::formatCurrency() und wandelt einen Gleitkomma-Betrag zusammen mit einem Währungscode in eine lokalisierte Zeichenkette um. Das Ergebnis richtet sich nach dem Locale des übergebenen NumberFormatter-Objekts – also z. B. 1.234,56 € für de_DE oder $1,234.56 für en_US.
Der Währungscode muss ein gültiger dreistelliger ISO-4217-Code sein (z. B. EUR, USD, CHF). Er überschreibt den im Formatter eventuell voreingestellten Währungscode und bestimmt neben dem Symbol auch die automatisch verwendete Nachkommastellen-Anzahl.
Die Funktion eignet sich überall dort, wo Geldbeträge benutzerfreundlich und kulturell korrekt dargestellt werden sollen – etwa in E-Commerce-Anwendungen, Rechnungsvorlagen oder Finanz-Dashboards. Gegenüber einer manuellen Zeichenkettenformatierung bietet sie volle Internationalierungs-Unterstützung über die ICU-Bibliothek.
Wird ein Fehler gemeldet (z. B. ungültiger Formatter), gibt die Funktion false zurück. Der genaue Fehlercode ist danach über numfmt_get_error_code() abrufbar.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $formatter Pflicht | NumberFormatter | Ein NumberFormatter-Objekt, das zuvor mit numfmt_create() oder new NumberFormatter() erstellt wurde. Das Locale dieses Objekts legt das Ausgabeformat fest (Tausendertrennzeichen, Dezimalzeichen, Symbolposition etc.). |
|
| $amount Pflicht | float | Der zu formatierende Geldbetrag als Gleitkommazahl. Negative Werte werden gemäß dem Locale korrekt dargestellt (z. B. mit vorangestelltem Minuszeichen oder in Klammern). | |
| $currency Pflicht | string | Dreistelliger ISO-4217-Währungscode in Großbuchstaben, z. B. EUR, USD oder JPY. Dieser Code bestimmt das angezeigte Währungssymbol sowie die standardmäßige Anzahl der Nachkommastellen. |
Rückgabewert
1.234,56 €. Bei einem Fehler (z. B. ungültiger Formatter oder Währungscode) wird false zurückgegeben; der Fehler kann mit numfmt_get_error_code() und numfmt_get_error_message() näher untersucht werden.Beispiele
Grundlegende Währungsformatierung für verschiedene Locales
<?php
// Deutsches Locale – Euro
$fmtDe = numfmt_create('de_DE', NumberFormatter::CURRENCY);
echo numfmt_format_currency($fmtDe, 1234567.89, 'EUR') . PHP_EOL;
// US-amerikanisches Locale – US-Dollar
$fmtUs = numfmt_create('en_US', NumberFormatter::CURRENCY);
echo numfmt_format_currency($fmtUs, 1234567.89, 'USD') . PHP_EOL;
// Schweizer Locale – Schweizer Franken
$fmtCh = numfmt_create('de_CH', NumberFormatter::CURRENCY);
echo numfmt_format_currency($fmtCh, 1234567.89, 'CHF') . PHP_EOL;Fehlerbehandlung und negativer Betrag
<?php
$fmt = numfmt_create('fr_FR', NumberFormatter::CURRENCY);
// Negativer Betrag
$result = numfmt_format_currency($fmt, -499.99, 'EUR');
if ($result === false) {
echo 'Fehler: ' . numfmt_get_error_message($fmt);
} else {
echo $result . PHP_EOL;
}
// Betrag in einer anderen Währung (JPY – keine Nachkommastellen)
$fmt2 = numfmt_create('ja_JP', NumberFormatter::CURRENCY);
echo numfmt_format_currency($fmt2, 12345, 'JPY') . PHP_EOL;// Wichtig · Fallstricke
Gleitkomma-Präzision: Da der Betrag als float übergeben wird, können bei sehr großen oder sehr kleinen Zahlen Rundungsfehler entstehen. Für buchhalterische Berechnungen empfiehlt es sich, intern mit Ganzzahlen (Cent-Beträgen) oder der bcmath-Erweiterung zu arbeiten und erst bei der Ausgabe zu konvertieren.
ICU-Abhängigkeit: Das genaue Ausgabeformat (Symbole, Leerzeichen, Tausendertrenner) hängt von der installierten ICU-Version ab und kann sich zwischen PHP-Versionen unterscheiden. Prüfe in Tests nicht auf exakte Strings, sondern auf enthaltene Teilstrings oder numerische Werte.
Ungültige Währungscodes führen nicht immer sofort zu false; manche ICU-Versionen zeigen stattdessen den unbekannten Code als Symbol an. Validiere Währungscodes daher vorab.