rfc:nullable_typehints

This is an old revision of the document!


PHP RFC: Declaring Nullable Types

Introduction

This RFC proposes new syntax to allow type declarations to also accept null without a default value; it also outlines how it will work in return types if that RFC is accepted.

Consider the function:

function foo(DateTime $time, $a) {}

In this situation you are not allowed to pass null for the$time parameter; this proposal allows you do pass null without using a default (= null).

Proposal

This proposal adds a marker ? to indicate that a type can also be null. This is allowed for any declared type including array and callable.

The ? marker can be placed on any parameter position, provided it does not violate inheritance rules:

function f(?callable $p, $a) {} // valid

Note that nullable parameters are required; you cannot omit the parameter like you can with a default parameter.

Position of ?

The ? marker goes before the type, as in ?Foo. If the ? came after the type, as in Foo?, then we'd have an issue if we ever supported generics; <Foo?> would conflict with a closing ?>. Putting it before the type does not have a conflict (<?Foo) because at that moment we are already inside of a <?php declaration.

Inheritance in Parameters

The ? marker cannot be removed in a sub-class; it can be added if not present in a super-class. This behavior is consistent with the Liskov substitution principle.

// Valid use: loosening the nullable marker in a parameter:
interface Fooable {
    function foo(Fooable $f);
}
interface LooseFoo extends Fooable {
    function foo(?Fooable $f);
}
// Invalid use: tightening the nullable marker in a parameter:
interface Fooable {
    function foo(?Fooable $f);
}
interface StrictFoo extends Fooable {
    function foo(Fooable $f);
}

Default Parameters and Nullable Types are not interchangeable

A default parameter and a nullable type are distinct and separate; you cannot use a default parameter where a nullable type existed in a parent; you cannot use a nullable type where a default parameter existed in a parent.

Return Types

If the RFC for Declaring Return Types passes, then nullable types would be extended to return types as well; this is a major motivator for introducing this new syntax as return types cannot specify a null default to get around the type check.

Here's an example of a binary tree that uses the nullable marker for both parameter and return types:

// Possible usage of ? modifier for both parameters and return types
class BinaryTree {
    public $value;
    private $right;
    private $left;
 
    function right(): ?BinaryTree {
        return $this->right;
    }
    function left(): ?BinaryTree {
        return $this->left;
    }
 
    function setRight(?BinaryTree $t) {
        $this->right = $t;
    }
    function setLeft(?BinaryTree $t) {
        $this->left = $t;
    }
}

It does not make sense to call setLeft without a parameter: $btree->setLeft(); what are you setting the left equal to? In this case the nullable type better reflects the ability to accept BinaryTree or null than a default parameter of null does.

Inheritance in Return Types

The nullable marker in return types behaves differently during inheritance than a parameter type does. In a return type, the null marker can be removed by a subclass, but it cannot be added:

interface Fooable {
    function foo(): ?Fooable;
}
interface StrictFooable extends Fooable {
    function foo(): Fooable; // valid
}
interface Fooable {
    function foo(): Fooable;
}
interface LooseFooable extends Fooable {
    function foo(): ?Fooable; // invalid
}

Differences from Default Parameters

The null marker does not have a default; it does not default to null. The following snippet would result in an error:

function f(?callable $p) {}
f(); // invalid; function f does not have a default

Proposed PHP Version(s)

This RFC targets 5.7 or 6.0, whichever comes first.

RFC Impact

To Backward Incompatibility

This RFC maintains backwards compatibility. This RFC does not deprecate the default value syntax.

To SAPIs

This RFC has no impact to SAPIs.

To Existing Extensions

TODO

New Constants

This RFC does not propose any new constants or ini defaults.

Open Issues

Make sure there are no open issues when the vote starts!

Unaffected PHP Functionality

This RFC does not deprecate the default value syntax. While there is some overlap of features between it and this RFC, they serve different purposes. As such, the default value syntax will remain.

Future Scope

TODO

Proposed Voting Choices

This RFC modifies the PHP language syntax and therefore requires a two-third majority of votes.

Patches and Tests

There is currently no patch.

Implementation

TODO

After the project is implemented, this section should contain

  1. the version(s) it was merged to
  2. a link to the git commit(s)
  3. a link to the PHP manual entry for the feature

References

TODO

rfc/nullable_typehints.1413389925.txt.gz · Last modified: 2017/09/22 13:28 (external edit)