Number::format
Formats an int or float into a locale-aware decimal string with thousands separators.
Number::format(int|float $number, ?int $precision = null, ?int $maxPrecision = null, ?string $locale = null): string|false- Added in Laravel 10.33.0
Parameters
| Parameter | Type | Description |
|---|---|---|
$$number | int|float | The value to format. |
$$precisionoptional | ?int= null | Exact number of fraction digits. Pads with trailing zeros. |
$$maxPrecisionoptional | ?int= null | Upper bound on fraction digits. Does not pad, and takes priority over $precision. |
$$localeoptional | ?string= null | ICU locale for the formatting rules. Falls back to the Number class locale. |
Return value
string|falseThe formatted number as a string, or false if the underlying NumberFormatter fails.
Errors
Throws RuntimeException when the intl PHP extension is not loaded.
Changelog
- PHP 10.33.0Introduced together with the Illuminate\Support\Number class.
- PHP 10.40.0The missing-intl RuntimeException message now names the Number method that was called.
Number::format() is a thin wrapper around PHP's NumberFormatter in decimal mode. Reach for it at the last step before a value reaches a view or an export, when you want grouping separators and a controlled number of decimals without hand-rolling number_format() and its hard-coded , and ..
The two precision knobs are not additive
The implementation checks $maxPrecision first and only falls back to $precision. Pass both and $precision is ignored outright. The difference between them is padding: precision: 2 forces exactly two fraction digits and will render 100,000.00, while maxPrecision: 2 is a ceiling and renders 100,000 for a whole number.
Pass neither and you get ICU's default for the locale, which for en is up to three fraction digits — so Number::format(1.23456) returns 1.235, quietly rounded.
Locale resolution
The locale comes from the argument, then from the Number class's own locale, which defaults to en. It is not the application locale set by App::setLocale(). Change it globally with Number::useLocale() in a service provider, or scope it with Number::withLocale().
Every locale-aware method on this class, this one included, requires the intl extension.
Example
When to use it
- Rendering an order line total or a stock count in a Blade view without hard-coding separators
- Formatting the same figure for a German and an English invoice from one code path
- Capping a computed average at two decimals in a CSV export without padding whole numbers
Frequently asked questions
Why is Number::format ignoring my precision argument?
Because you also passed maxPrecision, which wins. The method checks maxPrecision first and only falls back to precision when maxPrecision is null, so passing both silently discards precision. Drop one of them.
Does Number::format use the application locale?
No. It uses the Number class's own locale, which defaults to 'en' regardless of App::setLocale(). Set it with Number::useLocale() in a service provider, scope it with Number::withLocale(), or pass the locale argument per call.
Does Number::format need the intl extension?
Yes. It builds a NumberFormatter, and the class throws RuntimeException naming the called method when intl is not loaded. Only clamp(), trim() and pairs() work without it.
More examples
precision pads, maxPrecision does not
The precision column always shows two fraction digits — 5.00, 5.50, 5.13. The maxPrecision column shows 5, 5.5, 5.13: it rounds at two digits but never adds a zero that carries no information. Use precision for money columns that must line up, maxPrecision for prose.
<?php
use Illuminate\Support\Number;
$values = [5, 5.5, 5.125];
foreach ($values as $value) {
printf(
"%-7s precision:2 => %-6s maxPrecision:2 => %s\n",
$value,
Number::format($value, precision: 2),
Number::format($value, maxPrecision: 2)
);
}Scoping the locale for one block
Prints 1.234,5 then 1,234.5 then 1.234,5. withLocale() restores the previous locale in a finally block, so the third line proves the German default survived the closure even if the callback had thrown.
<?php
use Illuminate\Support\Number;
// In a service provider's boot() method:
Number::useLocale('de');
echo Number::format(1234.5), PHP_EOL;
$english = Number::withLocale('en', function () {
return Number::format(1234.5);
});
echo $english, PHP_EOL;
echo Number::format(1234.5), PHP_EOL;Guarding a report against a missing extension
On a box with intl the Number call runs and honours the configured locale; without it the fallback keeps the report rendering instead of throwing RuntimeException. Worth doing in a package that cannot dictate its host's PHP build.
<?php
use Illuminate\Support\Number;
function renderTotal(float $total): string
{
if (! extension_loaded('intl')) {
return number_format($total, 2);
}
return Number::format($total, precision: 2);
}
echo renderTotal(1234.5), PHP_EOL;
Discussion