PHP Manual: Format a number with grouped thousands

Description

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

Formats a number with grouped thousands and optionally decimal digits using the rounding half up rule.

Parameters

num: The number being formatted.
decimals: Sets the number of decimal digits. If 0, the decimal_separator is omitted from the return value. As of PHP 8.3.0, when the value is negative, num is rounded to decimals significant digits before the decimal point. Prior to PHP 8.3.0, negative values were ignored and handled the same as 0.
decimal_separator: Sets the separator for the decimal point.
thousands_separator: Sets the thousands separator.

Return Values

A formatted version of num.

Changelog

Version	Description
8.3.0	Added handling of negative values for `decimals`.
8.0.0	Prior to this version, number_format accepted one, two, or four parameters (but not three).
7.2.0	number_format was changed to not being able to return `-0`, previously `-0` could be returned for cases like where `num` would be `-0.01`.

Examples

Example #1 number_format Example

For instance, French notation usually use two decimals, comma (',') as decimal separator, and space (' ') as thousand separator. The following example demonstrates various ways to format a number:

<?php

$number = 1234.56;

// english notation (default)
echo number_format($number), PHP_EOL;
// 1,235

// French notation
echo number_format($number, 2, ',', ' '), PHP_EOL;
// 1 234,56

$number = 1234.5678;

// english notation without thousands separator
echo number_format($number, 2, '.', ''), PHP_EOL;
// 1234.57

?>

Example #2 A negative value for decimals

As of PHP 8.3.0, a negative value for decimals is used to round the number of significant digits before the decimal point.

<?php
$number = "1234.5678";
var_dump(number_format($number, -1));
var_dump(number_format($number, -2));
var_dump(number_format($number, -3));
?>

The above example will output:

string(5) "1,230"
string(5) "1,200"
string(5) "1,000"

number_format

Description

Parameters

Return Values

Changelog

Examples

See Also