GeneratorReturnBeforeCompletion

warning native on by default PHP ≥ 7.0

Group: Probable bugs

A generator exposes its return value only after it finishes. Complete iteration before calling getReturn.

Example

<?php
$g=(function(){yield 1;return 2;})(); $g->getReturn();

Reported:

• line 2: Finish the generator before reading its return value.

Detection

• A local assigned a call to a literal closure containing yield is immediately used as receiver of getReturn before any resume/iteration/next/send/throw operation. Report the method call; unknown calls or escape discard proof.
• Require an unconditional directly executed nondelegating yield in the generator body prefix before any terminating or ambiguous operation. Merely finding a yield somewhere is insufficient. Exclude dead or conditional yields, nested-scope yields, prior unconditional returns, and yield-from delegation, including delegation to an empty iterable.
• The first statement of the literal closure body must be an expression statement whose expression is a direct nondelegating yield. Preceding assignments, conditionals or other statements do not establish this initial suspended state; yield-from is excluded.
• The method name is matched case-insensitively, and the result does not have to be discarded. The call is reported when the statement directly after the assignment is an expression statement, a return or an echo that evaluates the call before anything else: the path from the call up to the statement may only pass through parentheses, unary operators and casts, the value of an assignment to a plain variable, the left operand of a binary operator, the condition of a ternary, the first argument of a call to a named function, and the first echo operand.
• Resolve builtin functions, classes, constants and methods; user-defined lookalikes are excluded. Follow only bounded local proof in one lexical scope.
• Emit one finding per violating operation, not per supporting evidence statement. When the proof is inconclusive, nothing is reported.

Exceptions (no report)

• Do not report unresolved or shadowed builtin names, unknown values, or incomplete receiver/type provenance. Unknown calls, aliases escaping, and intervening writes invalidate local proof. Similar code outside the stated detection contract is not a finding.
• Do not report a read that another part of the same statement may precede or skip: a later array element, argument or echo operand, a right operand, a ternary branch, an argument of a method or dynamic call, an assignment to a non-plain target, a closure or arrow function body, or the head of a control structure.
• Both standard suppression forms suppress this native ID.

Fix

None. Choosing a repair requires intent or additional runtime information.

PHP versions

Requires PHP 7.0 or later.

Configure

In custos.json:

{
  "rules": {
    "GeneratorReturnBeforeCompletion": {
      "enabled": false
    }
  }
}

Suppress

Before the statement or declaration (or the first statement of the file):

// @custos-ignore GeneratorReturnBeforeCompletion