Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.syntblaze.com/llms.txt

Use this file to discover all available pages before exploring further.

The never type is a bottom return type introduced in PHP 8.1 that indicates a function or method will never complete its normal execution cycle. When a function is declared with the never return type, it guarantees to the PHP engine and static analyzers that the program flow will halt, throw an exception, or enter an infinite loop before reaching the implicit return at the end of the function scope. 
function terminateExecution(): never {
    exit();
}

​
Execution Mechanics and Enforcement

To satisfy the never type constraint, the function must terminate the current execution context via one of the following mechanisms:
  1. Invoking exit() or die().
  2. Throwing an Exception or Error.
  3. Executing an infinite loop (e.g., while (true) {}).
The PHP engine enforces the never constraint using two distinct mechanisms depending on how the rule is violated:
  • Compile-Time Enforcement: Any explicit return statement inside a never-returning function (including a bare return; or returning a value) is caught during compilation and results in a Fatal error.
  • Runtime Enforcement: If the function execution reaches the closing brace (an implicit return), PHP throws a TypeError at runtime.
// Compile-time Fatal error: A never-returning function must not return
function explicitReturn(): never {
    return;
}

// Runtime TypeError: never-returning function must not implicitly return
function implicitReturn(): never {
    $x = 1 + 1;
}

​
Type Theory and Subtyping

In type theory, never represents the empty set of values, making it the bottom type. Consequently, never is a subtype of every other type in PHP’s type system, including void and mixed. Because of return type covariance, a subclass method can narrow a parent class’s return type to never regardless of the parent’s original return type declaration. 
class Base {
    public function execute(): int {
        return 42;
    }
}

class Child extends Base {
    // Valid: 'never' is a subtype of 'int'
    public function execute(): never {
        throw new LogicException();
    }
}
Conversely, due to contravariance rules, a parent method returning never cannot be overridden by a method returning any other type, as there is no type narrower than never.

​
Structural Restrictions

The PHP engine enforces strict rules regarding the placement and combination of the never type:
  • Return Type Exclusive: It can only be used as a return type. It is strictly prohibited as a parameter type, property type, or class constant type.
  • Standalone Type: It cannot be combined in a union or intersection type. Declarations such as never|string or never&Countable will result in a compile-time fatal error.
// Fatal error: never cannot be used as a parameter type
function process(never $value): void {}

// Fatal error: never cannot be used in a union type
function fetch(): never|array {}

​
Distinction from void

While both void and never indicate the absence of a returned value, their control flow guarantees differ fundamentally. A void function completes its execution and returns control to the calling scope (implicitly returning null). A never function strictly forbids control from ever returning to the calling scope.
Master PHP with Deep Grasping Methodology!Learn More