CatchVariableOverwritesLocal

warning native off by default

Group: Probable bugs

A catch variable shares its surrounding local scope. Use a different name when the previous local value is needed after exception handling. This inspection is disabled by default because the intended policy or use can vary.

Example

<?php
$result="ready"; try{work();}catch(Throwable $result){} echo $result;

Reported:

• line 2: Use a different catch variable to preserve the local value.

Detection

• A simple local has a definite non-exception assignment before try; a catch binds that same name and the variable is read after try without reassignment. Require lexical same-scope statements and a reachable throwing operation.
• The catch path must reach the later read while retaining the caught exception binding. Exclude catches that terminate by return/throw/exit, reassign or unset the local, and finally blocks that restore or replace its value. Unknown catch/finally operations discard the retained-binding proof.
• Exclude terminating catches and any assignment, increment/decrement or unset of the catch variable in the catch body or finally. These operations invalidate the retained exception-binding proof; do not treat the subsequent read as an overwrite hazard.
• 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.
• Both standard suppression forms suppress this native ID.

Fix

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

PHP versions

Available throughout supported PHP 5.3–8.5 where the referenced builtin/extension is available. Respect syntax/version-specific receiver contracts; unavailable APIs are not this rule’s concern.

Configure

In custos.json:

{
  "rules": {
    "CatchVariableOverwritesLocal": {
      "enabled": true
    }
  }
}

Suppress

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

// @custos-ignore CatchVariableOverwritesLocal