PHP RoundingMode::cases() Method: Usage and Examples

Lists the predefined RoundingMode enum cases supported by round().

The examples focus on the operation itself, including the important distinction: RoundingMode::HalfEven and other cases are used as the mode argument for round().

What It Does

Use the examples below to observe the behavior on a small dataset before extending it to application code.

Syntax and Return Value

RoundingMode::cases(): array

The displayed signature describes the API or identifies any correction or optional dependency. When a parameter is optional, supply it only when the task requires it.

Declared return type: array. Read the behavior notes for important cases such as empty collections and destructive iteration.

Example 1: Basic Use

PHP 8.4 and later accepts RoundingMode enum cases with round; positive and negative half-way values expose differences among rounding rules.

<?php
foreach (RoundingMode::cases() as $mode) {
    echo $mode->name . ": " . round(2.5, 0, $mode) . PHP_EOL;
}

Output from a successful local PHP 8.4 run:

HalfAwayFromZero: 3
HalfTowardsZero: 2
HalfEven: 2
HalfOdd: 3
TowardsZero: 2
AwayFromZero: 3
NegativeInfinity: 2
PositiveInfinity: 3

Example 2: Checking Behavior

PHP 8.4 and later accepts RoundingMode enum cases with round; positive and negative half-way values expose differences among rounding rules.

<?php
foreach (RoundingMode::cases() as $mode) {
    echo $mode->name . ": " . round(3.5, 0, $mode) . PHP_EOL;
}

Output from a successful local PHP 8.4 run:

HalfAwayFromZero: 4
HalfTowardsZero: 3
HalfEven: 4
HalfOdd: 3
TowardsZero: 3
AwayFromZero: 4
NegativeInfinity: 3
PositiveInfinity: 4

Example 3: Practical Example

PHP 8.4 and later accepts RoundingMode enum cases with round; positive and negative half-way values expose differences among rounding rules.

<?php
foreach (RoundingMode::cases() as $mode) {
    echo $mode->name . ": " . round(-2.5, 0, $mode) . PHP_EOL;
}

Output from a successful local PHP 8.4 run:

HalfAwayFromZero: -3
HalfTowardsZero: -2
HalfEven: -2
HalfOdd: -3
TowardsZero: -2
AwayFromZero: -3
NegativeInfinity: -3
PositiveInfinity: -2

Important Behavior and Edge Cases

RoundingMode was introduced in PHP 8.4; cases are enum objects, not strings.

Comparison with Related Approaches

Common Beginner Mistakes

Key Takeaways

• Lists the predefined RoundingMode enum cases supported by round().
• RoundingMode was introduced in PHP 8.4; cases are enum objects, not strings.
• RoundingMode::HalfEven and other cases are used as the mode argument for round().

Use RoundingMode::cases when its documented behavior matches the problem. Test the relevant edge cases in your own runtime before deploying it.