How combining PHP flags works for function calls

Here I talk a bit about how combining PHP flags work and why we use a vertical bar to combine them.

What can flags do with functions?

Some PHP functions have a parameter called $options that allow changing how it operates. One or many flags can be passed into this field to configure the function.

An example function is json_encode which has a number of flags, for example JSON_HEX_QUOT, JSON_HEX_TAG, JSON_HEX_AMP.

These can be used with the function such as

json_encode($data, JSON_HEX_QUOTE)

Or combining multiple flags:

json_encode($data, JSON_HEX_QUOTE | JSON_HEX_TAG)

Combining Flags with the bitwise or (vertical bar |)

Above I have shown how we combine multiple flags using the vertical bar symbol. In the background each flag is actually a number representing a bit mask. For example three flags could be represented as:

FLAG_1 = 001 = 1
FLAG_2 = 010 = 2
FLAG_3 = 100 = 4

Here each flag uses a different bit to represent the flag. Using bitwise or we can combine different flags for example:

FLAG_1 | FLAG_2 = 011 = 3
FLAG_2 | FLAG_3 = 110 = 6
FLAG_1 | FLAG_3 = 101 = 5

In each case, each bit position declares whether the flag has been set, the first bit position (right most) represents FLAG_1, the second (middle) FLAG_2, and the third (left most) FLAG_3.

When combining them we can use this bit pattern to check what flags are set. So we know that 011 means FLAG_1 and FLAG_2 has been set.

By combining flags we can use a single variable to represent multiple options for a function.

When might using + to combine flags cause issues

Since the representation of the bit masks are numbers (shown above) there may be some temptation to combine them using numerical addition (plus +). In many cases this will work identically, for example:

FLAG_1 | FLAG_2 = 011 = 3
FLAG_1 + FLAG_2 = 3 = 011

As an example above we can see that in the above case there is no difference.

However, sometimes flags are created which are a combination of basic flags. We could define a new flag.

FLAG_12 = FLAG_1 | FLAG_2 = 011 = 3
FLAG_12 = FLAG_1 + FLAG_2 = 3 = 011

Again for the above operations both numerical plus and bitwise or works identically. However we now can have issues if we use a flag that is a combination of two flags and one of its parts. Below is an example to explain this better:

FLAG_12 | FLAG_1 = 011 = 3
FLAG_12 + FLAG_1 = 4 = 100

In this case, numerical addition combines FLAG_1 again which then increases the numerical value by one. This then changes the binary representation to 100 and makes it a different flag. Whereas, using bitwise or keeps the binary representation as 011 representing FLAG_1 and FLAG_2.

This will only become a problem if you begin to add flags together multiple times. This could occur either by duplicating the flag in the call or using combination flags. If you are careful numerical additional can be used in place of bitwise or for combing flags.

However, using the binary or operator reduces the likelihood for confusion as all PHP documentation pages use this operator to combine flags. In addition to eliminating the risk of combining multiple of the same flags and

Summary

We can use flags to change the operation of different functions. When you want to use multiple flags you combine these with the bitwise or operation. We also learnt why numerical additional can be used to combine flags but mentioned the warnings when doing so.