number_format()

Die PHP-Funktion number_format() formatiert eine Zahl mit gruppierten Tausenderstellen und einer optionalen festen Anzahl von Dezimalstellen. Sie gibt einen string zurück, was sie zur bevorzugten Funktion für die Anzeige von Preisen, Statistiken und allen Zahlen macht, die ein Mensch lesen soll. Sie dient rein der Darstellung: Sie ändert den zugrunde liegenden Wert nicht, sondern nur dessen Ausgabe.

Dieses Kapitel behandelt die Syntax, alle Parameter, die Funktionsweise der Rundung und häufige Fallstricke, auf die man achten sollte.

Syntax

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

Parameter

Die Funktion gibt immer einen string zurück, sodass die Ausgabe direkt ausgegeben oder verkettet werden kann, aber nicht für weitere arithmetische Operationen verwendet werden sollte.

Einfaches Beispiel

Wird nur die Zahl übergeben, rundet number_format() auf eine ganze Zahl und fügt Kommas zwischen den Tausenderstellen ein:

Ausgabe:

1,235

Der Nachkommaanteil .56 bewirkte, dass der Wert auf 1235 aufgerundet wurde, und ein Komma wurde zwischen den Tausenderstellen eingefügt.

Dezimalstellen steuern

Übergeben Sie ein zweites Argument, um eine feste Anzahl von Dezimalstellen beizubehalten. Das ist es, was man für Geldbeträge fast immer möchte:

<?php
echo number_format(1234.567, 2);  // two decimal places
?>

Ausgabe:

1,234.57

Die dritte Dezimalstelle (7) wird auf die zweite Stelle gerundet. Beachten Sie, dass die Anzahl der Dezimalstellen auch dann fest ist, wenn der ursprüngliche Wert weniger Stellen hat — number_format(5, 2) gibt "5.00" zurück.

Benutzerdefinierte Trennzeichen (internationale Formate)

Das dritte und vierte Argument ermöglichen den Wechsel der Trennzeichen. Viele europäische Gebietsschemas verwenden einen Punkt für Tausender und ein Komma für den Dezimalpunkt:

<?php
$amount = 1234567.891;

echo number_format($amount, 2, ".", ",") . "\n";  // US / UK style
echo number_format($amount, 2, ",", ".") . "\n";  // German / Spanish style
echo number_format($amount, 2, ".", " ");         // space-grouped
?>

Ausgabe:

1,234,567.89
1.234.567,89
1 234 567.89

Um die Tausendertrennung vollständig zu entfernen, übergibt man einen leeren string als viertes Argument:

<?php
echo number_format(1234567.891, 2, ".", "");
?>

Ausgabe:

1234567.89

Funktionsweise der Rundung

number_format() rundet den Wert auf die gewünschte Genauigkeit nach dem Prinzip Runden weg von null — derselbe Standard wie bei der Funktion round(). Ein abschließendes .5 wird dem Betrag nach aufgerundet:

<?php
echo number_format(2.5) . "\n";   // 3
echo number_format(0.5) . "\n";   // 1
echo number_format(-9.5);         // -10
?>

Ausgabe:

3
1
-10

Häufige Fallstricke

• Das Ergebnis ist ein string, keine Zahl. Das Hinzufügen des Tausendertrennzeichens bedeutet, dass "1,235" + 1 nicht wie Arithmetik funktioniert. Wenn Sie weiter mit dem Wert rechnen müssen, formatieren Sie ihn erst in dem Moment, in dem Sie ihn anzeigen. Um Benutzereingaben, die Trennzeichen enthalten, wieder in eine Zahl umzuwandeln, verwenden Sie floatval() nachdem Sie die Gruppenzeichen entfernt haben.
• Es wird gerundet, nicht abgeschnitten. number_format(9.999, 2) gibt "10.00" zurück, nicht "9.99". Für Währungsberechnungen sollten Sie Ihre Werte gezielt runden, bevor Sie sie formatieren.
• Negative Null kann auftreten. Sehr kleine negative Zahlen können als -0.00 ausgegeben werden. Addieren Sie 0 zum Wert (oder verwenden Sie abs() bei nahezu null-Werten), wenn Sie das vermeiden möchten.
• Für gebietsschemaabhängige Währungsformate (Symbole, Gebietsschema-Regeln, Buchhaltungsformate) sollten Sie statt manueller string-Erstellung PHP's NumberFormatter aus der intl-Erweiterung in Betracht ziehen.

Verwandte Funktionen

• round() — eine Zahl auf eine bestimmte Genauigkeit runden und einen float zurückgeben.
• sprintf() und printf() — Zahlen (und andere Werte) mit %-Platzhaltern wie %.2f formatieren.
• floatval() — einen string wieder in eine Gleitkommazahl umwandeln.
• PHP-Mathematikfunktionen — die umfangreichere Sammlung numerischer Hilfsfunktionen.

Übungen