PHP 8.4: New rounding modes in round() function

Version8.4
TypeNew Feature

The round() function rounds a float value to the nearest integer or a decimal value of a specified precision. It supports various rounding modes, and PHP 8.4 adds four new rounding methods.

round(3.14, precision: 0, mode: PHP_ROUND_HALF_UP); // 3.0
round(3.14, precision: 1, mode: PHP_ROUND_HALF_UP); // 3.1
round(3.15, precision: 0, mode: PHP_ROUND_HALF_UP); // 3.0
round(3.5,  precision: 0, mode: PHP_ROUND_HALF_UP); // 4.0

Prior to PHP 8.4, the round() function supported four rounding methods:

  • PHP_ROUND_HALF_UP: Rounds the number away from zero when it is halfway there, making 1.5 into 2 and -1.5 into -2. Constant value int(1).
  • PHP_ROUND_HALF_DOWN: Rounds the number towards zero when it is halfway there, making 1.5 into 1 and -1.5 into -1. Constant value int(2).
  • PHP_ROUND_HALF_EVEN: Rounds the number towards the nearest even value when it is halfway there, making both 1.5 and 2.5 into 2. Constant value int(3).
  • PHP_ROUND_HALF_ODD: Rounds the number towards the nearest odd value when it is halfway there, making 1.5 into 1 and 2.5 into 3. Constant value int(4).

In PHP 8.4, the round() function supports the four following new rounding methods:

  • PHP_ROUND_CEILING: Rounds the number to the nearest integer bigger than the number, making 1.1 and 1.5 to 2 and -1.1 and -1.5 to -1. When the $precision parameter is 0, the return value is identical to the return value of the ceil function. Constant value int(5).
  • PHP_ROUND_FLOOR: Rounds the number to the nearest integer lower than the number, making 1.1 and 1.9 to -1, and -1.9 and -1.1 to -2. The return value is identical to the return value of the floor function. Constant value int(6).
  • PHP_ROUND_TOWARD_ZERO: Rounds the number towards zero, making 1.9 and 1.1 to 1 and -1.9 and -1.9 to -1. Constant value int(7).
  • PHP_ROUND_AWAY_FROM_ZERO: Rounds the number away from zero, making 1.1 and 1.9 to 2 and -1.1 and -1.9 to -2. Constant value int(8).

The following table summarizes the return values with examples:

0.8 1.1 1.5 1.9 -0.8 -1.1 -1.5 -1.9
PHP_ROUND_HALF_UP 1 1 2 2 -1 -1 -2 -2
PHP_ROUND_HALF_DOWN 1 1 1 2 -1 -1 -1 -2
PHP_ROUND_HALF_EVEN 1 1 2 2 -1 -1 -2 -2
PHP_ROUND_HALF_ODD 1 1 1 2 -1 -1 -1 -2
PHP_ROUND_CEILING 1 2 2 2 -0 -1 -1 -1
PHP_ROUND_FLOOR 0 1 1 1 -1 -2 -2 -2
PHP_ROUND_TOWARD_ZERO 0 1 1 1 -0 -1 -1 -1
PHP_ROUND_AWAY_FROM_ZERO 1 2 2 2 -1 -2 -2 -2

Rounding with Intl NumberFormatter

The NumberFormatter class from the Intl extension also provides rounding functionality with the added benefit of localizing the numbers.

NumberFormatter class also supports the same rounding modes, configured as an attribute (NumberFormatter::ROUNDING_MODE) to the object. The precision is set with the NumberFormatter::FRACTION_DIGITS attribute:

$formatter = new \NumberFormatter("en-US", \NumberFormatter::DECIMAL);
$formatter->setAttribute(NumberFormatter::FRACTION_DIGITS, 0);
$formatter->setAttribute(NumberFormatter::ROUNDING_MODE, NumberFormatter::ROUND_HALFUP);

$formatter->format(1.1);

The following table shows the corresponding NumberFormatter::ROUNDING_MODE attribute values for each round() rounding mode.

round mode NumberFormatter::ROUNDING_MODE value
PHP_ROUND_HALF_UP NumberFormatter::ROUND_HALFUP
PHP_ROUND_HALF_DOWN NumberFormatter::ROUND_HALFDOWN
PHP_ROUND_HALF_EVEN NumberFormatter::ROUND_HALFEVEN
PHP_ROUND_HALF_ODD NumberFormatter::ROUND_HALFODD
PHP_ROUND_CEILING NumberFormatter::ROUND_CEILING
PHP_ROUND_FLOOR NumberFormatter::ROUND_FLOOR
PHP_ROUND_TOWARD_ZERO NumberFormatter::ROUND_DOWN
NumberFormatter::ROUND_TOWARD_ZERO
PHP_ROUND_AWAY_FROM_ZERO NumberFormatter::ROUND_UP
NumberFormatter::ROUND_AWAY_FROM_ZERO

New Intl NumberFormatter::ROUND_ constants

The NumberFormatter class in PHP 8.4 also declares the following three constants:

  • NumberFormatter::ROUND_TOWARD_ZERO (with value int(2)): An alias for NumberFormatter::ROUND_DOWN, to be consistent with the round() function's PHP_ROUND_TOWARD_ZERO mode.
  • NumberFormatter::ROUND_AWAY_FROM_ZERO (with value int(3)): An alias for NumberFormatter::ROUND_UP, to be consistent with the round() function's PHP_ROUND_AWAY_FROM_ZERO mode.
  • NumberFormatter::ROUND_HALFODD (with value int(8)): to complement NumberFormatter::ROUND_HALFEVEN functionality, but this constant was not declared prior to PHP 8.4.

Backward Compatibility Impact

PHP_ROUND_CEILING, PHP_ROUND_FLOOR, PHP_ROUND_TOWARD_ZERO, and PHP_ROUND_AWAY_FROM_ZERO are new constants declared in PHP 8.4.

The NumberFormatter class from the Intl extension adds NumberFormatter::ROUND_TOWARD_ZERO as an alias for NumberFormatter::ROUND_DOWN, and NumberFormatter::ROUND_AWAY_FROM_ZERO as an alias for NumberFormatter::ROUND_UP.

Further, the Intl NumberFormatter class also declares a new NumberFormatter::ROUND_HALFODD that provides the same functionality as round() with mode PHP_ROUND_HALF_ODD. This constant was not declared prior to PHP 8.4, although NumberFormatter::ROUND_HALFEVEN already existed.

Related Changes

RFC Discussion Implementation