PHP 8.2: Allow null and false as standalone types

Version8.2
TypeNew Feature

PHP 8.0 added support for Union Types, which made it possible to declare a type as a union of two or more types. It allowed false and null as possible types for a Union Type, but disallowed their use as standalone types.

Prior to PHP 8.2, it was only possible to use null and false as parts of Union Types:

function foo(): string|null {}
function strpos(): int|false {}

Attempting to use null or false types as standalone types (i.e without being part of a union type) resulted in a compile-time fatal error in PHP versions PHP 8.0 and PHP 8.1:

function foo(): null {}
function bar(): false {}
Fatal error: Null can not be used as a standalone type in ... on line ...
Fatal error: False can not be used as a standalone type in ... on line ...

In PHP 8.2 and later, using null and false as standalone types is allowed. The snippet that resulted in fatal errors above no longer throws any errors in PHP 8.2 and later. This makes PHP's type system more expressive and complete to be able to precisely declare the return, parameter, and property types.

Further, PHP 8.2 and later allow using Union Types with null|false, which resulted in an error in older PHP versions.

PHP functions and methods that had to use PHPDoc comments to provide accurate type information can directly declare the type in the function itself:

  class AnonUser extends User {
-     /**
-      * @return false
-      */
-     public function isAdmin(): bool {
+     public function isAdmin(): false {
          return false;
      }
  }

Distinction between void and null return types

Note that functions declared with a null return type must explicitly return null, or the function call results in a TypeError exception. Functions that do not explicitly return a value, either by having no return statement at all, or by omitting the return value (return;) may continue to use the void type as a return type.

The following example throws a TypeError exception because it should have been declared with a void type instead of a null return type.

function foo(): null {}
foo();
TypeError: foo(): Return value must be of type null, none returned in ...:...

Unless null is a return type, declaring the function with a void or never return type is the more appropriate approach.

Nullability in null type

If a type is declared null, it cannot be marked "nullable" with the ?null syntax, as it results in a redundant type declaration. PHP throws an error on compile-time if it encounters one:

function doNotMakeSense(): ?null {}
Fatal error: null cannot be marked as nullable in ... on line ...

Related Changes

Backwards Compatibility Impact

Prior to PHP 8.2, it was not allowed to use null and false as standalone types. PHP 8.2 and later allows them as standalone types, and this should not cause any compatibility issues in older PHP versions.

It is not possible to back-port this functionality to older PHP versions.

RFC Discussion Implementation