A "never" function is checked at compile time and runtime, and may still throw

[MircoBabin]

Affected page

https://www.php.net/manual/en/language.types.never.php

Current issue

• There is no mention that a "never" function is checked by the compiler. And that the check is that no "return;" is used.
• There is no mention that a "never" function can produce a TypeError at runtime.
• There is no mention that a "never" function can still throw an Exception.
• There is no mention that "never" is not a type, but only a return-only type.

Suggested improvement

Mention these points.

Additional context (optional)

• Never can throw a TypeError at runtime:

// Simulate auto loading
$php = 
<<<'EOD'
    class Unknown
    {
        public static function Nothing()
        {
        }
    }
EOD;
eval($php);

function NeverReturns() : never
{
    Unknown::Nothing();
    // exit;
}

NeverReturns();

// Fatal error: Uncaught TypeError: NeverReturns(): never-returning function must not implicitly return in /in/GMMAC:19
// Stack trace:
// #0 /in/GMMAC(21): NeverReturns()
// #1 {main}
//  thrown in /in/GMMAC on line 19

[DanielEScherzer]

There is no mention that a "never" function is checked by the compiler. And that the check is that no "return;" is used.

We should add that, something like "Attempting to include a return statement in a never function is a compile-time error, even if the return would not be reached during execution."

---

There is no mention that a "never" function can produce a TypeError at runtime.

We should add that, something like "If control flow reaches the end of a never function without exiting, throwing an exception, or entering an infinite loop, a TypeError is thrown."

---

There is no mention that a "never" function can still throw an Exception.

Currently already says in the second sentence (bolding added)

This means that it either calls exit(), throws an exception, or is an infinite loop.

---

There is no mention that "never" is not a type, but only a return-only type.

Currently already says in the first sentence (bolding added)

never is a return-only type indicating the function does not terminate.

---

@MircoBabin do you want to send a patch to address the first two?