What is never return type in PHP 8.1

Question

PHP 8.1 introduces never return type, what is it? and what is the difference between never and void?

Answer 1

never type declaration introduced to be used as a return type hint for functions that never have return statement neither implicit nor explicit. And must be terminated by throwing an exception or exiting using exit/die functions.

function redirect(string $uri): never 
{
    header('Location: ' . $uri);
    exit();
}

Here redirect is called a never-returning function, because:

1) It has no return statement defined explicitly.

function redirect(string $uri): never 
{
    exit();
    return 'something';
}

Will prodcue:

PHP Fatal error: A never-returning function must not return

2) It has no return statement defined implicitly.

function redirect(string $uri): never
{
    if (false) {
        header('Location: ' . $uri);
        exit();
    }
}

Since the condition here is never satisfied, the execution jump over the if statement returning an implicit NULL which will result in:

PHP Fatal error: Uncaught TypeError: redirect(): never-returning function must not implicitly return

3) It ends it's execution with an exit function

void vs never

• void can have return; but never can't.
• never enforces that a function throws or is terminated with exit/die but void does not.
• never is a subtype of every other type in PHP’s type system, including void (this allows return type covariance).
• Both don't allow returning a value.
• Both can't be used as a parameter or a property type.
• Both can't be used as a return type of an arrow function.
• Both can only be used as a standalone type (no union or intersection is allowed).

When to choose void over never and vice versa?

You should declare a function return type void when you expect PHP to execute the next statement after the function call. And you should declare it never when you don't expect PHP to execute the next statement after that function call.

Answer 2

With never (PHP 8.1) you can safeguard a function for that it never returns, e.g. if you want to ensure that an endless loop created would really be endless (from the perspective of the call site):

<?php

function eternity(string $forEternity): never
{
    start:
    usleep(1000);
    goto start;
}

eternity('the future');
// <- we are here only after the next big-bang, not in this current universe.

This code is super-simplified, normally forgetting the goto statement here would trigger the error.

Endless loops are normally also not necessary to guard for (as normally we never want them to happen), but never is useful for a function to die(), exit() or throw an Exception, always.

Again, although these three ways to leave a function are not recommended in standard control flow (the first two are even controlling the running process in some SAPIs). But finally (no pun intended), it is possible to have the IDE and tooling see that a function never returns right from the return type information encoded in the code. This then also includes humans who are using such tools or who are reading the code.

---

With void (PHP 7.1) you safeguard that a function never returns a type, including the bottom type never (as you can only use void or never).

<?php

function back_from_eternity(string $forEternity): void
{
    usleep(100000); // not so long

    return $forEternity
}

$echo = back_from_eternity('soon');

Allows PHP to prevent the echo back from eternity as well as the reader to spot that the $echo = (and whatever is done afterwards with that variable) still needs the usual maintenance / debugging / testing or development.

• Compare: Void as return type

---

Both have the benefit that they throw when they are violated so the program will never ever continue as-is and render the function call returns void (all puns intended).

Any side-effects from calling the function should still be considered. It's normally about them.