Add roundingMode parameter to Number::format()

[ecantok]

Illuminate\Support\Number::format() and Illuminate\Support\Number::currency() methods use PHP’s NumberFormatter under the hood, but the rounding mode cannot currently be configured.
NumberFormatter defaults to NumberFormatter::ROUND_HALFEVEN (banker’s rounding), which often produces unexpected results:

Number::format(12.5, 0); // "12" due to NumberFormatter::ROUND_HALFEVEN

By contrast, developers commonly expect ROUND_HALFUP, which matches PHP’s number_format():

number_format(12.5, 0); // "13"

Proposed Method:

public static function format(
    float|int|string $number,
    ?int $precision = null,
    ?int $maxPrecision = null,
    ?string $locale = null,
    ?int $roundingMode = null // new parameter
){
    // generate $formatter = new NumberFormatter...

    if (! is_null($roundingMode)) {
        $formatter->setAttribute(NumberFormatter::ROUNDING_MODE, $roundingMode);
    }
    //  ....
}

public static function currency(
    int|float $number,
    string $in = '',
    ?string $locale = null,
    ?int $precision = null,
    ?int $roundingMode = null // new parameter
    )
{
    // generate $formatter = new NumberFormatter...

    if (! is_null($roundingMode)) {
        $formatter->setAttribute(NumberFormatter::ROUNDING_MODE, $roundingMode);
    }
    //  ....
}

Example Usage

use NumberFormatter;
use Illuminate\Support\Number;
Number::format(
    12.5,
    precision: 0,
    roundingMode: NumberFormatter::ROUND_HALFUP
); // "13"

Number::currency(
    12.5,
    precision: 0,
    roundingMode: NumberFormatter::ROUND_HALFUP
); // "$13"

Rounding mode constants come from PHP’s intl extension:
https://www.php.net/manual/en/class.numberformatter.php#intl.numberformatter-constants.unumberformatroundingmode

[ismaildasci]

This is a valid feature request! The banker's rounding (ROUND_HALFEVEN) default can definitely be confusing.

Current workaround:

You can use withLocale combined with a custom formatter:

use NumberFormatter;

$formatter = new NumberFormatter('en', NumberFormatter::DECIMAL);
$formatter->setAttribute(NumberFormatter::ROUNDING_MODE, NumberFormatter::ROUND_HALFUP);
$formatter->setAttribute(NumberFormatter::FRACTION_DIGITS, 0);
echo $formatter->format(12.5); // "13"

Or create a macro:

// In AppServiceProvider
Number::macro('formatRoundUp', function ($number, $precision = 0) {
    $formatter = new NumberFormatter(Number::defaultLocale(), NumberFormatter::DECIMAL);
    $formatter->setAttribute(NumberFormatter::ROUNDING_MODE, NumberFormatter::ROUND_HALFUP);
    $formatter->setAttribute(NumberFormatter::FRACTION_DIGITS, $precision);
    return $formatter->format($number);
});

// Usage
Number::formatRoundUp(12.5, 0); // "13"

For the feature request itself:

I think adding a roundingMode parameter makes sense. It's backward compatible and aligns with how NumberFormatter works internally. You might want to submit a PR for this - looks like a reasonable addition!

[ecantok]

Pull request created! #58514

unfortunately my pull request was rejected

[MrYamous]

This workaround looks overcomplicated, unfortunately the PR were rejected