# RFC: Nullable Types

- Status: Implemented (PHP 7.1)
- Authors: Levi Morrison levim@php.net
- Date: 2014-04-10
- Version: 1.0
- Original: https://wiki.php.net/rfc/nullable_types
- Page: https://externals.io/rfc/nullable_types
- More for agents: search with https://externals.io/search.md?q={query} · RFCs at https://externals.io/rfc.md · JSON API at https://externals.io/api · documentation at https://externals.io/llms.txt

## Votes

### Accept explicitly nullable types? (2/3 affirmative required) (closed)

Yes: 41 · No: 2

Voters: ajf (Yes), beberlei (Yes), bishop (Yes), bwoebi (No), colinodell (Yes), daverandom (Yes), davey (Yes), derick (Yes), dmitry (Yes), francois (Yes), galvao (Yes), guilhermeblanco (Yes), hywan (Yes), jhdxr (Yes), jwage (Yes), kalle (Yes), kguest (Yes), klaussilveira (Yes), lcobucci (Yes), lstrojny (Yes), malukenho (Yes), mariano (Yes), mbeccati (Yes), mcmic (Yes), mfonda (Yes), mgocobachi (Yes), mike (Yes), nikic (Yes), ocramius (Yes), omars (Yes), peehaa (Yes), philstu (Yes), pierrick (Yes), pollita (Yes), salathe (Yes), sammyk (Yes), stas (No), svpernova09 (Yes), till (Yes), tpunt (Yes), trowski (Yes), weierophinney (Yes), zimt (Yes)

### Merge which features? (majority wins) (closed)

Both nullable parameter and return types: 44 · Only nullable return types: 1

Voters: ajf (Both nullable parameter and return types), beberlei (Both nullable parameter and return types), bishop (Both nullable parameter and return types), bwoebi (Both nullable parameter and return types), colinodell (Both nullable parameter and return types), danack (Both nullable parameter and return types), daverandom (Both nullable parameter and return types), davey (Both nullable parameter and return types), derick (Both nullable parameter and return types), dragoonis (Both nullable parameter and return types), francois (Both nullable parameter and return types), galvao (Both nullable parameter and return types), guilhermeblanco (Both nullable parameter and return types), hywan (Both nullable parameter and return types), jhdxr (Both nullable parameter and return types), jwage (Both nullable parameter and return types), kalle (Both nullable parameter and return types), kguest (Both nullable parameter and return types), kinncj (Both nullable parameter and return types), klaussilveira (Both nullable parameter and return types), lstrojny (Both nullable parameter and return types), malukenho (Both nullable parameter and return types), marcio (Both nullable parameter and return types), mariano (Both nullable parameter and return types), mcmic (Both nullable parameter and return types), mfonda (Both nullable parameter and return types), mgocobachi (Both nullable parameter and return types), mike (Both nullable parameter and return types), nikic (Both nullable parameter and return types), ocramius (Both nullable parameter and return types), omars (Both nullable parameter and return types), peehaa (Both nullable parameter and return types), philstu (Both nullable parameter and return types), pierrick (Both nullable parameter and return types), pollita (Both nullable parameter and return types), rdohms (Both nullable parameter and return types), salathe (Both nullable parameter and return types), sammyk (Both nullable parameter and return types), stas (Only nullable return types), svpernova09 (Both nullable parameter and return types), till (Both nullable parameter and return types), tpunt (Both nullable parameter and return types), trowski (Both nullable parameter and return types), weierophinney (Both nullable parameter and return types), zimt (Both nullable parameter and return types)

## Discussions on the mailing list

- [Improving PHP's type system](https://externals.io/message/92252.md) — started on 2016-04-13, 94 messages
- [\[RFC\] Nullable Types](https://externals.io/message/92273.md) — started on 2016-04-14, 25 messages
- [\[RFC\] Pre-vote notice for Nullable Types](https://externals.io/message/93100.md) — started on 2016-05-06, 7 messages
- [\[RFC\]\[VOTE\] Nullable Types](https://externals.io/message/93149.md) — started on 2016-05-10, 16 messages
- [my concept ( new PDO FETCH MODE )](https://externals.io/message/99002.md) — started on 2017-05-10, 2 messages

---

## Introduction

It is common in many programming languages including PHP to allow a variable to be of some type or null. This null often indicates an error or lack of something to return. This can already be done using PHP's dynamic type system by omitting type declarations. It can also be done for parameters in PHP by using a default parameter of null. However, this does not work for return types which do not have a concept of a default value. This RFC proposes a unified way to add nullable types to both parameters and returns.

## Proposal

This proposal adds a leading question mark symbol (`?`) to indicate that a type can also be `null`. Nullable types can be formed from any currently permitted type. Nullable types are permitted anywhere type declarations are allowed but are subject to some inheritance rules which are outlined later in the RFC.

Here are a few examples to demonstrate basic functionality:

```php
function answer(): ?int  {
    return null; //ok
}
 
function answer(): ?int  {
    return 42; // ok
}
 
function answer(): ?int {
    return new stdclass(); // error
}
```

```php
function say(?string $msg) {
    if ($msg) {
        echo $msg;
    }
}
 
say('hello'); // ok -- prints hello
say(null); // ok -- does not print
say(); // error -- missing parameter
say(new stdclass); //error -- bad type
```

### Return Types

When subtyping a return type the nullability can be removed by a subclass, but it cannot be added:

```php
interface Fooable {
    function foo(): ?Fooable;
}
interface StrictFooable extends Fooable {
    function foo(): Fooable; // valid
}
```

```php
interface Fooable {
    function foo(): Fooable;
}
interface LooseFooable extends Fooable {
    function foo(): ?Fooable; // invalid
}
```

### Parameter Types

The nullable type 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.

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

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

### Default Values

#### Differences from default values

Parameters with a nullable type do not have a default value. If omitted the value does not default to `null` and will result in an error:

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

#### Relationship with default values

PHP's existing semantics allow giving a `null` default value for a parameter to make it nullable and optional:

```php
function foo_default(Bar $bar = null) {}
 
foo_default(new Bar); // valid
foo_default(null); // valid
foo_default(); // valid
```

This existing behaviour is not changed by this RFC. The new nullable type feature offers a subset of the functionality of `= null` with both making a parameter nullable but only `= null` making a parameter optional and have a default value:

```php
function foo_nullable(?Bar $bar) {}
 
foo_nullable(new Bar); // valid
foo_nullable(null); // valid
foo_nullable(); // INVALID!
```

As `= null` offers a superset of `?`'s functionality, it could be said that `= null` implies `?`. However, it is perfectly legal to use both to make a parameter's nullability explicit:

```php
function foo_both(?Bar $bar = null) {}
 
foo_both(new Bar); // valid
foo_both(null); // valid
foo_both(); // valid
```

Because a parameter with `= null` is a superset of `?`, you can use a parameter with a default value of null where a nullable type existed in the parent.

```php
interface Contract {
    function method(?Foo $foo): bool;
}
 
class Implementation implements Contract {
    function method(?Foo $foo = null): bool {
        return is_null($foo);
    }
}
```

The reverse is not true, however: you cannot use only a nullable type where a default value existed in the parent, because the parameter is no longer optional.

### PHP Version

This RFC targets PHP 7.1.

### Voting Choices

The vote for this RFC is split into two votes. One vote will be for accepting the idea of explicitly nullable types with the short-hand syntax. The second vote determines whether to merge only nullable return types or to also merge nullable parameter types as well.

Voting began Tuesday, May 10th, 2016 and will close on Friday, May 20th, 2016.

---

**Vote: Accept explicitly nullable types? (2/3 affirmative required)** — Yes: 41 · No: 2 (closed)

---

**Vote: Merge which features? (majority wins)** — Both nullable parameter and return types: 44 · Only nullable return types: 1 (closed)

### Patches and Tests

The pull request for this RFC is here: <https://github.com/php/php-src/pull/1893>.

## RFC Impact

### To Backward Compatibility

There is a backwards compatibility break in certain cases. This was previously fixed as a bug but it was decided that because of the BC break that it would be pushed to this RFC. See [bug 72119](https://bugs.php.net/bug.php?id=72119) for more info on the BC break.

This BC break is to reject parameter covariance for nullable types:

```php
interface Fooable {
    function foo(?Fooable $f);
}
interface StrictFoo extends Fooable {
    // Invalid; parent type allows null so subtype must also allow it
    function foo(Fooable $f);
}
```

However, it breaks this code:

```php
interface Fooable {
    function foo(array $f = null);
}
interface LooseFoo extends Fooable {
    function foo(array $f = []);
}
```

Such code should be modified to also allow null:

```php
interface LooseFoo extends Fooable {
    function foo(?array $f = []);
}
```

Note that more handling is probably necessary to make the code robust, but this small change is sufficient for any previously working code to continue to work.

### To Existing Extensions

Only extensions that deal with the AST need to be updated. They should be aware of the `ZEND_TYPE_NULLABLE` attribute that gets set when a `?` is present.

### To Union Types

Nullable types are a special case of union types where there only two types in the union, one of which is always `null`. If the [union\_types](https://externals.io/rfc/union_types) RFC is accepted then `?Foo` will be exactly equivalent to `Foo | Null`. The union types RFC will be responsible for intersecting decisions, such as whether `?` can be used in conjunction with other union types.

### 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

1. [Full union types](https://externals.io/rfc/union_types)

## Implementation

After the project is implemented, this section should contain

1. the version(s) it was merged to
2. a link to the [git commit](http://git.php.net/?p=php-src.git;a=commitdiff;h=9662259cb93ff04be80766bdade39d2e827e0e16)
3. a link to the PHP manual entry for the feature

## References

1. Discussion on [mailing list](http://news.php.net/php.internals/92273)
2. Background for multiple type enhancements: <http://news.php.net/php.internals/92252>