This is an old revision of the document!
PHP RFC: Allow null as standalone type
- Version: 0.1
- Date: 2021-10-02
- Author: George Peter Banyard, girgias@php.net
- Status: Under Discussion
- 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
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 1) 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.
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 SplFileObject::getChildren()
Proposal
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 { /* ... */ *} }
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.
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.
Patches and Tests
Links to any external patches and tests go here.
If there is no patch, make it clear who will create a patch, or whether a volunteer to help with implementation is needed.
Make it clear if the patch is intended to be the final patch, or is just a prototype.
For changes affecting the core language, you should also provide a patch for the language specification.
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