New in PHP 8: Union Types

This email is part of a series where I talk about the most interesting features of PHP 8.

Today we look at Union Types.

PHP introduced type hinting some time ago, with version 5.

Type hinting lets you specify the type of function arguments and function return values.
For example:

/*
* The $num argument must be a float.
* The function return value must be a Boolean.
*/
function myFunc(float $num): Bool
{}

Type hinting is very useful to make your code more robust and readable.
However, PHP still remains a weakly/dynamic typed language. Indeed, PHP functions are often designed to support different types for the same argument or for their return values.

We can talk about whether this is a good programming habit or not. But anyway, this is how things work in PHP.

Before PHP 8, if you wanted a function argument to assume two or three different types, you just could not use type hinting at all. You had to leave the argument without any type declaration.
And as a result, that argument's type could be of any type.

Union types solve this problem.
With PHP 8 union types, you can define one or more types for function arguments and return values.
For example, here the $num parameter can either be an integer or a float:

function myFunc(int|float $num)
{}

The same goes for return values.
The following function can return a Boolean (true/false) or a string:

function myFunc(int|float $num): bool|string
{}

NULL and FALSE types

With the old type hinting syntax, you can accept NULL arguments when using type hinting with the following syntax:

function myFunct(?string $str)
{}

Union types supports this too, but you can use the same syntax for NULLs as for other types:

function myFunct(string|null $str)
{}

Union types also let you specify the special false type, for arguments and for return values.
false is not a real type, but it is supported as a special type because some legacy code returns false on errors.

There are some limitations you need to be aware of, though:

You cannot use the false type together with the bool type
false cannot be the only accepted type
You cannot use the false type with the NULL type
The true special type does not exist!

For example, the following function can return a string or false:

function myFunct(): string|false
{}

Union types rules
There are some rules to follow when using union types:

You cannot specify the same type twice
You can use the void type for function return values, but not for arguments and class properties.
On top of that, the void type cannot be combined with other types.

Union types and class properties
You can use union types to specify the types of class properties.
For example, here the $a property in MyClass can be a string or an integer:

class MyClass
{
private string|int $a;
}

Union types and inherited classes
What happens if you inherit a class and you reimplement a method of the parent class?

If the parent class method uses union types for its arguments and/or return value, and if you want to change the accepted types, you must follow some rules.
The exact rules are a bit tricky, but you can simply follow these two simple rules of thumb:

Function arguments must allow the same types or more types.
Function return values must allow the same types or less types.

For example:

class BaseClass
{
public function classFunct(string|array $param): bool|null {}
}

class ChildClass extends BaseClass
{
public function classFunct(string|array|float $param): bool {}
}

You can find more details and specific rules here.

Union types: PROs and CONs

Union types provide the same advantages as type hinting, even when you need to allow more than one type.
This definitely helps improve your code readability and quality.

The question is: is PHP going to enforce strict typing more in the future?
On the one hand, union types let you use type hinting more often than before.
On the other hand, they remove the need to choose a single type for each argument (or for the return value) for developers who want to use type hinting.

So, it's not 100% clear if more or less strict typing rules can be expected in the future.
What do you think?