The `clamp` Function in PHP 8.6

Introduction

The clamp function is a new addition (RFC) to PHP 8.6 (to be released in November 2026), which will allow you to restrict a value within a specified range. This function is particularly useful when you want to ensure that a value does not exceed a lower or upper bound, such as when validating user input or performing calculations.

In this article, we're going to take a quick look at what the clamp function is, how you'll be able to use it in PHP 8.6, and how you can achieve similar functionality in earlier versions of PHP.

How to Use clamp in PHP 8.6

Let's start by looking at how to use the clamp function in PHP 8.6.

Basic Usage

The clamp function can be called like so:

$clampedValue = clamp($value, $min, $max);

As we can see, the function accepts three parameters:

• value: The value you want to clamp.
• min: The minimum value of the range.
• max: The maximum value of the range.

Here are some examples of how it might be used to clamp integers:

// Within the given range:
$clampedValue = clamp(value: 50, min: 10, max: 100)); // 50

// Below the minimum:
$clampedValue = clamp(value: 9, min: 10, max: 100)); // 10

// Above the maximum:
$clampedValue = clamp(value: 101, min: 10, max: 100)); // 100

As we can see, if the value is within the range defined by min and max, it is returned as-is. If the value is below the minimum, the minimum value is returned. If the value is above the maximum, the maximum value is returned.

Under the hood, the clamp function is essentially similar to the following:

function clamp(mixed $value, mixed $min, mixed $max) {
    // Error handling here...
    
    if ($value > $max) {
        return $max;
    }
    
    if ($value < $min) {
        return $min;
    }
    
    return $value;
}

Since it's comparing using < and >, this means it can be used with any type that supports these comparisons, such as strings, arrays and even some objects.

Let's look at some examples of how the clamp function can be used with different types of values. To keep this article concise, we'll only look at examples using the data types you'll likely use the clamp function with in your day-to-day work.

Clamping Floats and Integers

You can use clamp to restrict both float values to a given range:

clamp(value: 10.5, min: 0.2, max: 99.9); // 10.5
clamp(value: 0.1, min: 0.2, max: 99.9); // 0.2
clamp(value: 100.0, min: 0.2, max: 99.9); // 99.9

You can also use clamp to restrict int values to a given range:

clamp(value: 50, min: 10, max: 100); // 50
clamp(value: 9, min: 10, max: 100); // 10
clamp(value: 101, min: 10, max: 100); // 100

Clamping Non-Numerical Strings

If all three values are non-numerical strings, they'll be compared lexicographically. In its most basic form, this means the strings are compared character by character, just as you would when sorting strings in alphabetical order (like in a dictionary). The first character of each string is compared, and if they are equal, the second character is compared, and so on. If one string is a prefix of the other, the shorter string is considered to be less than the longer string. So, for example, "AAA" is less than "AAAA", and "A" is less than "B".

Here's a simple example of how the clamp function can be used with non-numerical strings:

clamp('D', 'A', 'Z'); // "D"
clamp('D', 'E', 'Z'); // "E"
clamp('D', 'A', 'C'); // "C"

Clamping Objects

Objects can also be clamped, provided they support < and > comparisons. For example, the DateTime and DateTimeImmutable classes both support comparisons using these two operators, so they can be used with the clamp function.

For example, you can use the clamp function to restrict a DateTimeImmutable object to a given range:

clamp(
    value: new DateTimeImmutable('2027-02-03'),
    min: new DateTimeImmutable('2027-01-01'),
    max: new DateTimeImmutable('2027-12-31'),
); // DateTimeImmutable('2027-01-08')

clamp(
    value: new DateTimeImmutable('2027-02-03'),
    min: new DateTimeImmutable('2027-03-01'),
    max: new DateTimeImmutable('2027-12-31'),
); // DateTimeImmutable('2027-03-01')

clamp(
    value: new DateTimeImmutable('2027-02-03'),
    min: new DateTimeImmutable('2027-01-01'),
    max: new DateTimeImmutable('2027-01-31'),
); // DateTimeImmutable('2027-01-31')

Things to Note

There are some things to keep in mind when using the clamp function:

• The function is defined in the global namespace.
• If the min value is greater than the max value, a ValueError will be thrown.
• If the min or max values are NAN, a ValueError will be thrown.

How to Use clamp Before PHP 8.6

If you want to use the clamp functionality in versions of PHP prior to 8.6, there are several approaches you can take.

Using min and max Functions

You can achieve the same result as the clamp function by using a combination of the min and max functions. Here's how you can do it:

$clampedValue = min(max($number, $min), $max);

You can then use this approach to clamp values in the same way as the clamp function:

// Within the given range:
$clampedValue = min(max(50, 10), 100); // 50

// Below the minimum:
$clampedValue = min(max(9, 10), 100); // 10

// Above the maximum:
$clampedValue = min(max(101, 10), 100); // 100

It's worth noting that this approach doesn't include the same error handling as the clamp function, so you may want to add additional checks to ensure that the min value is not greater than the max value and that neither of them are NAN.

Using Laravel's Number::clamp function

If you're using the Laravel framework, you can use the Illuminate\Support\Number::clamp method to achieve the same result as the previous snippets. Here's how you can use it:

use Illuminate\Support\Number;

// Within the given range:
$clampedValue = Number::clamp(value: 10, min: 50, max: 100); // 50

// Below the minimum:
$clampedValue = Number::clamp(value: 10, min: 9, max: 100); // 10

// Above the maximum:
$clampedValue = Number::clamp(value: 10, min: 101, max: 100); // 100

Under the hood, the Illuminate\Support\Number::clamp method is doing the following:

namespace Illuminate\Support;

use Illuminate\Support\Traits\Macroable;
use NumberFormatter;
use RuntimeException;

class Number
{
    // ...
  
    /**
     * Clamp the given number between the given minimum and maximum.
     *
     * @param  int|float  $number
     * @param  int|float  $min
     * @param  int|float  $max
     * @return int|float
     */
    public static function clamp(int|float $number, int|float $min, int|float $max)
    {
        return min(max($number, $min), $max);
    }
    
    // ...
}

As we can see, this approach is using the same min and max functions as the previous approach, but it's wrapped in a class method for convenience. It's also worth noting that due to the int|float type hinting, this method will only work with int and float values, so it won't support clamping strings or objects.

Conclusion

Hopefully, this article has given you a quick insight into the new clamp function that will be available in PHP 8.6, how it works, and how you can achieve similar functionality in earlier versions of PHP.

If you enjoyed reading this post, I'd love to hear about it. Likewise, if you have any feedback to improve future ones, I'd love to hear it.

You might also be interested in checking out my 220+ page ebook "Battle Ready Laravel" which covers similar topics in more depth.

Or, you might want to check out my other 440+ ebook "Consuming APIs in Laravel" which teaches you how to use Laravel to consume APIs from other services.

If you're interested in getting updated each time I publish a new post, feel free to sign up for my newsletter below.

Keep on building awesome stuff! 🚀