How to use bitmasks in PHP

Or other languages. It’s the same concept.

Bitmasks are as old as computing itself and, admittedly, were more useful in the days of memory scarcity and low-level programming. But there’s nothing to stop you using them today, when appropriate.

PHP makes use of bitmasks in many of its built-in functions. Consider:

json_encode($json, JSON_PRETTY_PRINT | JSON_UNESCAPED_SLASHES);

(my personal favourite way of calling json_encode…)

Every time you pass flags to json_encode—or any similar function, of course—you’re making use of a bitmask.

What’s a bitmask?

A bitmask / bitfield is a series of boolean values, stored in unique bits of an individual integer. You can define related flags in such a way that you can then use them in combination, in a single numeric value.

How a bitmask works

The second argument in the call to json_encode above is an integer, but we obtain it via bitwise logic. The pipe character (|) performs a bitwise OR. A ‘bitwise or’ is simply a series of bits obtained by inspecting two other binary values. A 1 bit in either input results in a 1 bit in the output. For example:

A bitmask uses this principle in conjunction with predefined values, each a power of 2. The two JSON constants we used above have the following binary representations:

That’s 2⁷ (128) for JSON_PRETTY_PRINT and 2⁶ (64) for JSON_UNESCAPED_SLASHES. Note that, because each value is an exact power of two, their binary equivalents only contain a single bit each. This is a vital property for a bitmask.

A bitmask in action

Consider a function, sanitise. It performs various transformations on a string to clean it up: trimming & folding whitespace, converting it into lowercase, and so on. Here’s how it might look as a ‘standard’ function:

function sanitise(string $str, bool $trim, bool $fold, bool $case)
{
    if ($trim) {
        $str = trim($str);
    }
    if ($fold) {
        $str = preg_replace('/\s\s+/', ' ', $str);
    }
    if ($case) {
        $str =…