PHP RFC: Allow null as standalone type

• Version: 0.2
• Date: 2021-10-02
• Author: George Peter Banyard, girgias@php.net
• Status: Withdrawn
• Target Version: PHP 8.2
• Implementation: https://github.com/php/php-src/pull/7546
• First Published at: http://wiki.php.net/rfc/null-standalone-type
• Superseded by: https://wiki.php.net/rfc/null-false-standalone-types

null corresponds to PHP's unit type, i.e. the type which holds a single value.

It is currently not possible to use null as a type declaration on its own, as per its nature of it being the unit type, it cannot hold any information.

There are a couple of motivations outlined below:

PHP has added support for the top type mixed in PHP 8.0, the bottom type never in PHP 8.1, and support for composite types in PHP 8.0 with union types, and 8.1 with intersection types.

The inability to type the unit type in PHP is a deficiency which should be resolved.

The false literal type was added with the introduction of union types ¹⁾ and can only be used in union types, however this is not exactly true as null|false is disallowed.

The only way to currently type this edge case is by using bool|null which gives the false impression that the value may also be true, making this type information less useful for humans and static analysers.

There are instances of this type declaration being needed within some of PHP's built-in functions, one example being gmp_random_seed()

This edge case might be expanded if literal types are added and cannot be used as standalone type, as null|1 would also be disallowed.

A parent class might define a method as following: public function foo(): ?T, since PHP 7.4 covariance of return (and contravariance of parameter) types are supported , therefore it is possible for a child class to provide more precise type information if it always returns a value of type T: public function foo(): T.

However, the opposite isn't true, if the child method returns always null it must still use the original function signature and can only provide this information through documentation.

A method, from a built-in PHP class, which could benefit from declaring its return value as null is SplFileObject::getChildren()

A function always returns a value in PHP, even if its return type is declared as void where NULL is the value returned. The union type RFC did not include support for null for the following reason:

The null type is only allowed as part of a union, and can not be used as a standalone type. Allowing it as a standalone type would make both function foo(): void and function foo(): null legal function signatures, with similar but not identical semantics. This would negatively impact teachability for an unclear benefit.

As explained previously, there are clear reasons as to why one may need to use null as a return type, as void is not a subtype of any other type and lives on its own in the type hirarchy.

Moreover, a function which has a void return type must only use return; wherease one with null must use return null;.

Add support for using null as a stand-alone declaration type, wherever type declarations are currently allowed.

class Nil {
    public null $nil = null;
 
    public function foo(null $v): null { /* ... */ *}
} 

Although this proposal allows to now write null|false and false|null it does not support writing ?false, or using implicit nullability (function test(false $v = null)), this is to continue to make a distinction that false is a non-standalone type.

Trying to mark null as nullable will result in a compile time error, in line with PHP's current type resolving redundancy rules.

Reflection support is as expected with the notable exception that null|false will produce a ReflectionUnionType instead of a ReflectionNamedType contrary to other null|T types.

This RFC does not contain any backwards incompatible changes.

Next minor version, i.e. PHP 8.2.

As per the voting RFC a yes/no vote with a 2/3 majority is needed for this proposal to be accepted.

GitHub pull request: https://github.com/php/php-src/pull/7546

After the project is implemented, this section should contain

• the version(s) it was merged into
• a link to the git commit(s)
• a link to the PHP manual entry for the feature