{
    "slug": "php_never_type",
    "term": "never Return Type (PHP 8.1)",
    "category": "php",
    "difficulty": "intermediate",
    "short": "Declaring a function's return type as never signals it always throws or exits — enabling static analysers to prune unreachable code branches.",
    "long": "The never return type (PHP 8.1) declares that a function will never return normally — it always throws an exception, calls exit(), or enters an infinite loop. This is stricter than void (which returns, just without a value). Static analysers use never to mark code after a call as unreachable and to verify that all branches of a conditional throw rather than fall through. Practical uses: exception factory helpers (throw new InvalidArgumentException(...) extracted into a method), router 404 handlers that always abort(), and test assertion helpers that always throw on failure. A function declared never that actually returns causes a TypeError at runtime.",
    "aliases": [
        "never return type PHP",
        "PHP never",
        "always-throw function"
    ],
    "tags": [
        "php8",
        "php",
        "type-system"
    ],
    "misconception": "The never return type is the same as void. void functions return normally with no value. never functions never return at all — they always throw or exit. Static analysers use never to prove unreachability of code after such calls.",
    "why_it_matters": "The never return type declares that a function will never return normally — it must throw an exception or call exit(). Static analysers use it to prune unreachable code paths after such calls.",
    "common_mistakes": [
        "Not using never on redirect-and-exit helpers — analysers cannot tell that code after the call is unreachable.",
        "Using void instead of never — void means the function returns without a value; never means it doesn't return at all.",
        "Declaring never on a function that can sometimes return normally — this is a type error PHP will enforce.",
        "Not understanding that never makes the function a dead end in control flow — useful for abort, throw helpers."
    ],
    "when_to_use": [],
    "avoid_when": [],
    "related": [
        "never_return_type",
        "type_declarations",
        "phpstan_levels",
        "dead_code_detection"
    ],
    "prerequisites": [
        "type_declarations",
        "exception_handling",
        "strict_types"
    ],
    "refs": [
        "https://www.php.net/manual/en/language.types.never.php"
    ],
    "bad_code": "// Without 'never' — analyser doesn't know redirect() exits:\nfunction redirect(string $url): void { // Should be: never\n    header('Location: ' . $url);\n    exit();\n}\n\nredirect('/login');\n$user = getCurrentUser(); // Analyser flags this as reachable — false positive\n// With 'never', analyser correctly marks this as unreachable",
    "good_code": "function abort(int $code): never {\n    http_response_code($code);\n    exit();\n}\n\nfunction fail(string $msg): never {\n    throw new RuntimeException($msg);\n}",
    "quick_fix": "Use 'never' as the return type for functions that always throw or always call exit/die — it signals to static analysis that code after the call is unreachable",
    "severity": "low",
    "effort": "low",
    "created": "2026-03-15",
    "updated": "2026-03-22",
    "citation": {
        "canonical_url": "https://codeclaritylab.com/glossary/php_never_type",
        "html_url": "https://codeclaritylab.com/glossary/php_never_type",
        "json_url": "https://codeclaritylab.com/glossary/php_never_type.json",
        "source": "CodeClarityLab Glossary",
        "author": "P.F.",
        "author_url": "https://pfmedia.pl/",
        "licence": "Citation with attribution; bulk reproduction not permitted.",
        "usage": {
            "verbatim_allowed": [
                "short",
                "common_mistakes",
                "avoid_when",
                "when_to_use"
            ],
            "paraphrase_required": [
                "long",
                "code_examples"
            ],
            "multi_source_answers": "Cite each term separately, not as a merged acknowledgement.",
            "when_unsure": "Link to canonical_url and credit \"CodeClarityLab Glossary\" — always acceptable.",
            "attribution_examples": {
                "inline_mention": "According to CodeClarityLab: <quote>",
                "markdown_link": "[never Return Type (PHP 8.1)](https://codeclaritylab.com/glossary/php_never_type) (CodeClarityLab)",
                "footer_credit": "Source: CodeClarityLab Glossary — https://codeclaritylab.com/glossary/php_never_type"
            }
        }
    }
}