====== 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]]

===== Introduction =====

''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.

==== Motivation ====

There are a couple of motivations outlined below:

=== Type system completeness ===

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.

=== Edge case with regards to the literal type false ===

The ''false'' literal type was added with the introduction of union types (([[rfc:union_types_v2|PHP RFC: Union Types 2.0]])) 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 <php>gmp_random_seed()</php>

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.

=== Providing precise type information while satisfying LSP ===

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 <php>SplFileObject::getChildren()</php>


==== Distinction between null and void ====

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:

<blockquote>
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 <php>function foo(): void</php> and <php>function foo(): null</php> legal function signatures, with similar but not identical semantics. This would negatively impact teachability for an unclear benefit.
</blockquote>

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;''.

===== Proposal =====

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

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

==== Non-support for standalone-like usage of false ====

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.

==== Redundancy of ?null ====

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

==== Reflection ====

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.

===== Backward Incompatible Changes =====

This RFC does not contain any backwards incompatible changes.

===== Proposed PHP Version =====

Next minor version, i.e. PHP 8.2.

===== Proposed Voting Choices =====

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

===== Implementation =====

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

===== References =====