Number::forHumans

Converts a large number to a readable scale phrase such as 1.23 million.

Signature
Number::forHumans(int|float $number, int $precision = 0, ?int $maxPrecision = null, bool $abbreviate = false): string|false
  • Added in Laravel 10.33.0

Parameters

ParameterTypeDescription
$$numberint|floatThe value to summarise. Negatives keep their sign.
$$precisionoptionalint= 0Exact fraction digits in the mantissa, padded with zeros.
$$maxPrecisionoptional?int= nullUpper bound on fraction digits. Takes priority over $precision.
$$abbreviateoptionalbool= falseUse the letter suffixes K, M, B, T, Q instead of the spelled scale words.

Return value

string|falseThe number followed by a scale word such as ' thousand' or ' million', or by a letter suffix when $abbreviate is true.

Errors

Throws RuntimeException when the intl PHP extension is not loaded, because the mantissa is rendered by Number::format().

Changelog

  • PHP 10.33.0Introduced together with the Illuminate\Support\Number class.
  • PHP 10.40.0A float zero now returns '0' instead of falling through the exponent maths.

See also

Number::abbreviateNumber::formatNumber::spellNumber::fileSize

Number::forHumans() writes the scale out in words — 1 thousand, 490 thousand, 1.23 million — where Number::abbreviate() would give 1K, 490K, 1.23M. Reach for it in running prose, email subject lines and headings, where a letter suffix reads as jargon. Set abbreviate: true and you get the letters back; that flag is exactly what Number::abbreviate() passes.

The scale words are hard-coded English

There is no $locale parameter, and the suffix array in the source is a literal ' thousand', ' million', ' billion', ' trillion', ' quadrillion'. Setting Number::useLocale('de') changes how the digits are formatted, because the mantissa goes through Number::format(), but the word stays English. The result is a mongrel like 1,23 million. For a translated application, run the output through your own translation strings or format the parts yourself.

Rounding

The default precision of 0 means 1500000 becomes 2 million. Use maxPrecision when you want a decimal only where it carries information. Values below 1000 come back with no scale word at all.

Example

Try it yourself
Loading editor…
Press Run to execute the code.

When to use it

  • Writing a headline such as 'over 2.5 million requests served' in a status page
  • Summarising a row count in an admin notification email
  • Describing a large figure in prose where 2.5M would read as jargon

Frequently asked questions

How do I translate 'million' into another language?

You cannot through this method — the scale words are hard-coded English literals and forHumans() takes no locale argument. Strip the suffix with a regex and translate it yourself, or build the string from Number::format() plus your own translation keys.

What is the difference between forHumans and abbreviate?

Only the suffix set. forHumans() spells out ' thousand' and ' million'; abbreviate() is the same call with abbreviate: true and yields K and M. Pass abbreviate: true to forHumans() and the two are identical.

Why does Number::forHumans(1500000) say 2 million?

The default precision is 0, so the mantissa 1.5 rounds to 2. Pass maxPrecision: 1 to get '1.5 million', which shows the decimal only when it is non-zero.

More examples

Words versus letters, side by side

The middle column reads 850, 1 thousand, 45.3 thousand, 1.23 million, 7.9 billion, 3.2 trillion; the right column gives the same values as 850, 1K, 45.3K, 1.23M, 7.9B, 3.2T. Note that the sub-1000 row is identical in both — no suffix is applied below the first scale.

Example · php
<?php

use Illuminate\Support\Number;

$values = [850, 1000, 45300, 1230000, 7900000000, 3200000000000];

foreach ($values as $value) {
    printf(
        "%-16s %-16s %s\n",
        $value,
        Number::forHumans($value, maxPrecision: 2),
        Number::forHumans($value, maxPrecision: 2, abbreviate: true)
    );
}

The locale only reaches the digits

Prints '1.23 million' then '1,23 million'. The decimal separator switched to a comma but the word did not translate, because forHumans() has no locale parameter and its suffix table is a hard-coded English literal.

Example · php
<?php

use Illuminate\Support\Number;

echo Number::forHumans(1230000, precision: 2), PHP_EOL;

Number::withLocale('de', function () {
    echo Number::forHumans(1230000, precision: 2), PHP_EOL;
});

Translating the scale word yourself

In a booted application with a numbers.php language file, this turns '2.5 million' into '2,5 Millionen' under a German locale. Splitting the suffix off is the only way to localise the word, since the method itself offers no hook.

Example · php
<?php

use Illuminate\Support\Number;

function humanised(int $value): string
{
    $formatted = Number::forHumans($value, maxPrecision: 1);

    return preg_replace_callback(
        '/ (thousand|million|billion|trillion|quadrillion)$/',
        fn ($m) => ' '.__('numbers.'.$m[1]),
        $formatted
    );
}

echo humanised(2500000), PHP_EOL;

Related

number abbreviatenumber formatnumber spellnumber filesize

Discussion

  • Be the first to comment on this lesson.