HeapIterationConsumesCollection

warning native off by default PHP ≥ 5.3

Group: Probable bugs

Iterate a clone to preserve the heap. This opt-in inspection applies the policy stated in Detection.

Example

Finding with the rule explicitly enabled:

<?php
$h = new SplMinHeap(); $h->insert(4); foreach ($h as $item) {}

Reported:

• line 2: Iterate a clone to preserve the heap.

Detection

• Enabled policy requires heap preservation. Report foreach directly over a resolved builtin SplHeap subtype or SplPriorityQueue object; each iterator step extracts from the heap. Highlight the foreach iterable expression. A clone expression satisfies preservation, written inline or bound to a local as described in E3.
• Emit one finding per violating operation. Flow facts require a reachable path with no intervening mutation, escaped alias, unknown call involving the tracked value or analysis-budget exhaustion. Uncertain facts cannot prove a violation.

Exceptions (no report)

• Exclude clone iterables and classes with overridden iterator operations, IteratorAggregate wrappers and unknown concrete heap type. Policy is supplied by enabling the rule, never inferred from later variable names.
• Exclude shadowed builtin symbols, unresolved required types, incomplete syntax and unsupported PHP versions.
• E3. Exclude a plain local variable iterable that provably holds a private copy. The proof is syntactic and limited to the variable's own scope (the whole file for top-level code): the variable has exactly one write, a plain $copy = clone <expr>; expression statement that runs on every ordinary path to the loop, and every other mention of the variable is a foreach iterable, the receiver of a method call or the argument of the builtin count(). Any other mention keeps the report: a second or conditional assignment, a compound or by-reference assignment, a clone nested in a larger expression, passing or storing the variable, a closure capture, global/static, or use as a loop target. Variable variables, $GLOBALS, extract(), parse_str(), include/require and eval anywhere in the scope also keep the report. Properties and array elements are never treated as private copies.

Fix

No automatic fix. Choosing a repair requires runtime information, error-handling policy or a semantic decision.

All edits use exact byte ranges, preserve comments and evaluation order, and require syntax supported by the target PHP version. A fix must never add an evaluation or silently change unrelated arguments.

PHP versions

Minimum PHP 5.3.

Options

None. Enabling the rule declares the policy stated in Detection; the rule is disabled by default.

Configure

In custos.json:

{
  "rules": {
    "HeapIterationConsumesCollection": {
      "enabled": true
    }
  }
}

Suppress

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

// @custos-ignore HeapIterationConsumesCollection