====== PHP RFC: Allow null and false as stand-alone types ======

  * Version: 0.3
  * Date: 2022-02-20
  * Author: George Peter Banyard, <girgias@php.net>
  * Status: Implemented
  * Target Version: PHP 8.2
  * Implementation: [[https://github.com/php/php-src/commit/6039c07a3afd64a42c9b9f1ed994ca971db67a1e]]
  * First Published at: [[http://wiki.php.net/rfc/null-standalone-type]]

===== Introduction =====

''null'' corresponds to PHP's unit type, i.e. the type which holds a single value. ''false'' is a literal type of type ''bool''.

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.

Moreover, ''false'' has traditionally been used instead of ''null'' to convey error state. This is the main reason why ''false'' was introduced as a literal type with the union type RFC(([[rfc:union_types_v2|PHP RFC: Union Types 2.0]])).


==== 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 can only be used in union types, however this is not exactly correct as ''null|false'' is disallowed.

The only way to currently type this edge case is by using ''bool|null'' which gives the wrong 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 stand-alone type, as a return type of ''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>.

The same applies to ''false'' where a userland extension for <php>UConverter::transcode()</php> might decided to always return ''false''
and cannot currently type this properly.


==== 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 stand-alone type. Allowing it as a stand-alone 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 hierarchy.

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

===== Proposal =====

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

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

<PHP>
class Falsy {
    public false $nil = false;
    
    public function foo(false $v): false { /* ... */ *}
} 
</PHP>

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

A concrete case of how this looks like:
<PHP>
<?php
function dumpType(ReflectionUnionType $rt) {
    echo "Type $rt:\n";
    echo "Allows null: " . ($rt->allowsNull() ? "true" : "false") . "\n";
    foreach ($rt->getTypes() as $type) {
        echo "  Name: " . $type->getName() . "\n";
        echo "  String: " . (string) $type . "\n";
        echo "  Allows Null: " . ($type->allowsNull() ? "true" : "false") . "\n";
    }
}

function test1(): null|false { }
function test2(): ?false { }


dumpType((new ReflectionFunction('test1'))->getReturnType());
dumpType((new ReflectionFunction('test2'))->getReturnType());
</PHP>
Will produce the following output:
<code>
Type false|null:
Allows null: true
  Name: false
  String: false
  Allows Null: false
  Name: null
  String: null
  Allows Null: true
Type false|null:
Allows null: true
  Name: false
  String: false
  Allows Null: false
  Name: null
  String: null
  Allows Null: true
</code>

==== Example ====

We take an example from unit testing but it can be applied to other more general cases,
where a class which implements an interface always returns ''null''.

<PHP>
class User {}

interface UserFinder
{
    function findUserByEmail(): User|null;
}

class AlwaysNullUserFinder implements UserFinder
{
    function findUserByEmail(): null
    {
        return null;
    }
}
</PHP>

Currently it is not possible to write this code in PHP as it gives the error:
<blockquote>Fatal error: Null can not be used as a standalone type</blockquote>

This means that an incorrect ''User|null'' return definition needs to used for the ''findUserByEmail()'' method.
That leads to further confusion as a static analyzer analysing that class will give a 'method can never return type User' error.

The same problem exists for interfaces that have a return type that is a union of false with another type.

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

Voting started on 2022-03-12 and will end on 2022-03-26.
<doodle title="Accept Allow null and false as stand-alone types RFC?" auth="girgias" voteType="single" closed="true">
   * Yes
   * No
</doodle>

===== Implementation =====

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

After the project is implemented, this section should contain

  * Version 8.2.0
  * Commit: https://github.com/php/php-src/commit/6039c07a3afd64a42c9b9f1ed994ca971db67a1e
  * a link to the PHP manual entry for the feature

===== References =====