PHP RFC: Void Return Type

• Version: 0.1
• Date: 2015-02-14
• Author: Andrea Faulds, ajf@ajf.me
• Status: Under Discussion
• First Published at: http://wiki.php.net/rfc/void_return_type

The Return Types RFC has introduced return types to PHP. While there is already a means to specify that any value may be returned (by omitting the return type), there is no means to specify that no value can be returned, unlike many other languages with return types. This is unfortunate, as this can be useful for documentation and error-checking purposes. In particular, it makes it clear that a function performs an action, rather than producing a result. This RFC proposes the introduction of a void return type for this purpose.

Support for a new void return type is added. It requires that a function not return any value:

function should_return_nothing(): void {
    return 1; // Catchable fatal error: should_return_nothing() must not return a value, integer returned
}
should_return_nothing();

It accepts either an implicit return, or an explicit value-less return:

function lacks_return(): void {
    // valid
}
lacks_return();
 
function returns_nothing(): void {
    return; // valid
}
returns_nothing();

However, it does not accept returning a NULL value:

function returns_null(): void {
    return NULL; // Catchable fatal eerror: returns_null() must not return a value, null returned
}
returns_null();

This might seem odd given that return; is technically equivalent. However, allowing NULL would also allow this:

function returns_null2(): void {
    $x = some_computation(); // produces null most of the time
    return $x; // Catchable fatal error: returns_null() must not return a value, null returned
}
returns_null2();

If we were to allow returning a value which evaluates to null, we'd have to allow the above, and this doesn't make sense: a void function shouldn't be trying to return a value.

Furthermore, there is a code style point to be made here. return; signals different intent to return NULL;. The former returns control flow and, while it does implicitly produce a null return value, signals that the return value is unimportant. The latter, on the other hand, explicitly produces a null return value, suggesting that the null value is significant.

The void type cannot be used for parameters:

function foobar(void $foo) { // Fatal error: void cannot be used as a parameter type
}

A void return type cannot be changed during inheritance. You can see this as either because return types are invariant, or because they are covariant and nothing is a subclass of void.

class Foo
{
    public function bar(): void {
    }
}
 
class Foobar extends Foo
{
    public function bar(): array { // Fatal error: Declaration of Foobar::bar() must be compatible with Foo::bar(): void
    }
}

Like the scalar types proposed by the Scalar Type Hints RFC, the void return type does not become a reserved word, but is instead restricted from use in class and interface names. This avoids confusion while minimising backwards-compatibility breakage.

This is proposed for the next major version of PHP, currently PHP 7.

As this is a language change, a 2/3 majority is required. The vote is a straight Yes/No vote for accepting the RFC and merging the patch.

There is a patch for php-src with tests here: https://github.com/php/php-src/pull/1084 It is based on patch used by the Scalar Type Hints RFC, since it already contains the infrastructure for reserving class and interface names for parameter and return types. However, should that RFC fail to pass, it would be possible to base the patch directly on master.

There is currently no patch for the language specification.

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

• v0.1 - Initial version