PHP number_format(): Tausendertrennzeichen und Dezimalen

number_format($number, $decimals) liefert die Zahl als String mit Tausendertrennzeichen und einer festen Anzahl von Nachkommastellen: number_format(1234567.891, 2) liefert "1,234,567.89". Mit einem Argument rundet es auf eine ganze Zahl: number_format(1234567.891) ist "1,234,568".

<?php
$amount = 1234567.891;

echo number_format($amount), "\n";            // no decimals
echo number_format($amount, 2), "\n";         // 2 decimals
echo number_format($amount, 2, ',', '.'), "\n"; // European style
echo number_format(0.129, 2), "\n";
echo number_format(-1234.567, 1), "\n";

Die vier Parameter

number_format(
    float $num,
    int $decimals = 0,
    ?string $decimal_separator = ".",
    ?string $thousands_separator = ","
): string

Das dritte Argument ist das Zeichen zwischen ganzzahligem Teil und Nachkommastellen, das vierte das Zeichen zwischen den Dreiergruppen von Ziffern. Beide können ein beliebiger String sein, auch ein leerer oder ein Multibyte-Zeichen. Ändere die Trennzeichen unten, um jede Schreibweise zu sehen:

<?php
$n = 1234567.891;

echo number_format($n, 2, '.', ','), "  US, UK, Japan\n";
echo number_format($n, 2, ',', '.'), "  Germany, Spain, Italy, Brazil\n";
echo number_format($n, 2, ',', ' '), "  France, Russia, Poland\n";
echo number_format($n, 2, '.', "'"), "  Switzerland\n";
echo number_format($n, 2, '.', ''), "  no separator\n";

Locale-Daten (CLDR) verwenden für Französisch ein schmales geschütztes Leerzeichen (U+202F) und für Russisch ein geschütztes Leerzeichen (U+00A0), damit eine Zahl nie über zwei Zeilen umbricht. In HTML übergibst du "\u{202F}" oder "\u{00A0}" als Trennzeichen statt eines einfachen Leerzeichens.

Eine Zahl ohne Tausendertrennzeichen formatieren

Übergib '' als viertes Argument. Du bekommst eine einfache Zahl mit fester Anzahl von Nachkommastellen, die Form, die Zahlungs-Gateways, CSV-Exporte und Werte von <input type="number"> erwarten:

<?php
$prices = [5, 19.9, 1234.5];

foreach ($prices as $p) {
    echo number_format($p, 2, '.', ''), "\n";
}

// Cents as an integer, for APIs that want the smallest unit
echo (int) round(19.9 * 100), "\n";

Für die letzte Zeile ist round() vor dem Cast wichtig: 19.9 * 100 wird als 1989.9999999999998 gespeichert, und (int) allein würde es auf 1989 abschneiden.

Wie number_format rundet

number_format() rundet Hälften von null weg, so wie round(), also wird 0.5 zu 1 und -2.5 zu -3. Es korrigiert außerdem den winzigen binären Fehler in Werten wie 2.675, weshalb es von sprintf('%.2f') abweichen kann:

<?php
foreach ([0.5, 1.5, 2.5, -2.5] as $x) {
    echo $x, " => ", number_format($x), "\n";
}

echo "\n";
echo number_format(2.675, 2), "  number_format\n";
echo sprintf('%.2f', 2.675), "  sprintf\n";
echo round(2.675, 2), "  round\n";

// PHP 8.3: negative decimals round to tens, hundreds, thousands
echo number_format(1234567, -3), "\n";

2.675 lässt sich binär nicht exakt speichern; der gespeicherte Wert liegt ein Haar darunter. sprintf() formatiert diesen gespeicherten Wert und bekommt 2.67, während number_format() und round() ihn als das 2.675 behandeln, das du geschrieben hast. Wenn du eine bestimmte Rundungsregel brauchst, rufst du vorher selbst round(), floor() oder ceil() auf (siehe Runden und Mathe) und übergibst das Ergebnis an number_format().

Geld und andere Währungen formatieren

number_format() weiß nichts über Währungen, also fügst du das Symbol selbst hinzu. Setze Minuszeichen vor das Symbol, und denk daran, dass der Yen keine Nachkommastellen hat:

<?php
function money(float $amount, string $symbol = '$'): string
{
    $sign = $amount < 0 ? '-' : '';
    return $sign . $symbol . number_format(abs($amount), 2);
}

echo money(1499.5), "\n";
echo money(-20), "\n";
echo money(1234.5, '€'), "\n";

// Japanese yen: no decimals, 円 after the number
echo number_format(1980), "円\n";
echo '¥' . number_format(128000), "\n";

Für eine Locale-bewusste Ausgabe mit der richtigen Position des Symbols für jedes Land erledigt NumberFormatter aus der Erweiterung intl die ganze Arbeit:

$fmt = new NumberFormatter('de_DE', NumberFormatter::CURRENCY);
echo $fmt->formatCurrency(1234.5, 'EUR'); // 1.234,50 € (a no-break space before €)

Dafür ist die Erweiterung intl nötig, die nicht überall installiert ist, also ist number_format() mit eigenem Symbol die portable Wahl.

Das Ergebnis ist ein String, keine Zahl

Das ist der häufigste Bug mit number_format(): einen Wert formatieren und dann damit rechnen. "1,234.50" ist kein numerischer String, also liest PHP nur die 1 vor dem Komma:

<?php
echo number_format(1234.5, 2) + 1;

Warning: A non-numeric value encountered in /home/index.php on line 2
2

Einen solchen String zurück an number_format() zu geben, ist noch schlimmer: Es wirft TypeError: number_format(): Argument #1 ($num) must be of type int|float, string given. Behalte die rohe Zahl zum Rechnen und formatiere erst in dem Moment, in dem du ausgibst. Wenn du einen formatierten String aus einem Formular oder einer Datei bekommst, entfernst du zuerst die Trennzeichen:

<?php
$total = 1234.5;
$display = number_format($total, 2);      // for output only

echo $display, "\n";
echo number_format($total + 100, 2), "\n"; // math on the number, then format

// Turning "1,234.50" back into a float
$input = '1,234.50';
$value = (float) str_replace(',', '', $input);
var_dump($value);

// European input "1.234,50"
$eu = '1.234,50';
$value = (float) str_replace(['.', ','], ['', '.'], $eu);
var_dump($value);

Für Auffüllen, Ausrichtung oder ein Pluszeichen vor der Zahl verwendest du stattdessen sprintf(); es fügt keine Tausendertrennzeichen ein, steuert aber Breite und Vorzeichen.