IteratorCountChangesRequiredPosition

warning native off by default

Group: Probable bugs

Identify a position-dependent current or key read on a locally allocated finite ArrayIterator after iterator_count consumes it, without rewind or seek. Unknown iterator implementations are excluded.

Detection

• Report a position-dependent current or key read on a locally allocated finite, non-empty ArrayIterator after iterator_count consumes it, without rewind or seek. Unknown iterator implementations are excluded.
• The count must be an iterator_count call that executes on every path to the read. Between the construction and the read, the iterator variable may only appear as an iterator_count argument or as the receiver of current, key, valid, next or count, none of which makes an exhausted cursor valid again. rewind and seek receivers are also accepted when they precede the last such count, which consumes the iterator again.
• Resolve builtin functions, classes, constants and methods, including imports and supported named arguments. Follow only bounded local facts within one lexical scope. Receiver and argument provenance must establish the specific API contract; variable names and comments never prove intent.
• Report one finding per violating operation. A reachable path, unchanged value identity and applicable API behavior are required. Intervening mutation, unknown calls involving tracked values, escaped aliases or exhausted analysis budgets invalidate proof.

Exceptions (no report)

• Exclude unresolved required symbols, user-defined lookalikes, incomplete syntax, unknown required values and unsupported versions.
• Both @custos-ignore IteratorCountChangesRequiredPosition and @noinspection IteratorCountChangesRequiredPosition suppress this native rule.
• Any other mention of the iterator variable between its construction and the read ends the proof, wherever it stands and whether or not it always executes: a foreach over the iterator (which rewinds it), a rewind or seek in a for header or a conditional branch, a wrapper such as new LimitIterator($it), an alias, a closure or arrow-function capture, an argument to any other call, an array-access write or another method call.
• An iterator built from an empty array literal: counting leaves it at the same invalid position it started at.

Fix

None. A repair requires a semantic decision or application error-handling policy.

PHP versions

Available in PHP 5.3–8.5 where the referenced API exists. Do not apply extension contracts when the resolved API is unavailable. Gate syntax and version-specific behavior to the configured target.

Configure

In custos.json:

{
  "rules": {
    "IteratorCountChangesRequiredPosition": {
      "enabled": true
    }
  }
}

Suppress

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

// @custos-ignore IteratorCountChangesRequiredPosition