README

Adds the support of the mathematical method clamp() for PHP.

[!IMPORTANT] Starting with PHP 8.6, this package will become obsolete as the clamp() function will be natively available in PHP. See the PHP RFC: clamp() function v2 for more details.

Installation

The recommended way of installing Larvatar is to use Composer. Run the following command to install it to your project:

composer require renfordt/clamp

Usage

The usage is basic and comparable to the C++ function:

clamp(
    $value, // The value to be clamped
    $min, // The minimum value to clamp to
    $max // The maximum value to clamp to
);

Alternatively you can use clampMinMax() which is a bit slower.

clampMinMax(
    $value, // The value to be clamped
    $min, // The minimum value to clamp to
    $max // The maximum value to clamp to
);

Accepted types

Following PHP 8.6's native clamp(), the arguments may be any mutually comparable values — integers, floats, strings, or comparable objects such as DateTimeInterface — and mixed combinations are allowed:

clamp(2, min: 1, max: 3);   // 2
clamp(0, min: 1, max: 3);   // 1
clamp(6, min: 1, max: 3);   // 3
clamp(2, 1.3, 3.4);         // 2
clamp(2.5, 1, 3);           // 2.5
clamp(0, 1.3, 3.4);         // 1.3
clamp(M_PI, -INF, INF);     // 3.141592653589793
clamp(NAN, 4, 6);           // NAN (a NAN value is returned unchanged)
clamp("a", "c", "g");       // "c"
clamp("d", "c", "g");       // "d"

clamp(
    new DateTimeImmutable('2025-08-01'),
    new DateTimeImmutable('2025-08-15'),
    new DateTimeImmutable('2025-09-15')
)->format('Y-m-d'); // 2025-08-15

Errors

A ValueError is thrown when the bounds are invalid:

clamp(4, 8, 6);
// ValueError: clamp(): Argument #2 ($min) must be smaller than or equal to argument #3 ($max)

clamp(4, NAN, 6);
// ValueError: clamp(): Argument #2 ($min) cannot be NAN

clamp(4, 6, NAN);
// ValueError: clamp(): Argument #3 ($max) cannot be NAN

Both clamp() and clampMinMax() behave identically, including these errors.

Why another package?

Even though there are some similar packages, this one focuses on different approaches.

First of all, the syntax is similar to c++ clamp function.

Secondly and more importantly, this package focuses on performance. Other packages uses the max($min, min($max, $num)) approach but this packages works with the following code:

if ($value > $max) {
    return $max;
} elseif ($value < $min) {
    return $min;
}
return $value;

Even though the readability is a bit worse, the performance is up to 2x faster. In most cases this is not noticeable, but in some cases there will be a benefit.

Over an iteration of 100.000 executions, the functions need the following times:

String

• clamp: 0.0035040378570557 sec
• clampMinMax: 0.0061681270599365 sec

Integer

• clamp: 0.0029380321502686 sec
• clampMinMax: 0.0056021213531494 sec

Float

• clamp: 0.0028560161590576 sec
• clampMinMax: 0.0062460899353027 sec