Boolean Return Null

ID

php.boolean_return_null

Severity

low

Remediation Complexity

trivial

Remediation Risk

low

Remediation Effort

low

Resource

Reliability

Language

Php

Tags

CWE:476, reliability

Description

Reports a return null; inside a function or method whose declared return type is the non-nullable boolean type (bool or boolean). The function promises a boolean but hands back null, breaking its own contract.

Rationale

Callers of a bool-returning function expect exactly two outcomes and write plain boolean logic around the result. A returned null forces every call site to add a null-check, and when it slips through, null is silently coerced to false in a condition — hiding the difference between "false" and "no answer". If a function genuinely needs a third state, its return type should say so with a nullable hint (?bool), which this rule deliberately leaves alone.

<?php
function isReady(): bool
{
    if ($pending) {
        return null;    // FLAW — bool contract violated
    }
    return true;        // OK
}

function maybeReady(): ?bool
{
    return null;        // OK — nullable hint permits null
}

Remediation

Return an actual boolean (true / false). If the absence of an answer is meaningful, widen the return type to ?bool so the nullability is explicit and callers handle it deliberately.

References