<?php

declare(strict_types=1);

use ast\Node;

use Phan\AST\InferPureAndNoThrowVisitor;

use Phan\Config;

use Phan\Library\FileCache;

use Phan\Parse\ParseVisitor;

use Phan\PluginV3;

use Phan\PluginV3\PluginAwarePostAnalysisVisitor;

use Phan\PluginV3\PostAnalyzeNodeCapability;

/**

* This file checks for empty statement lists in loops/branches.

* Due to Phan's AST rewriting for easier analysis, this may miss some edge cases.

*

* It hooks into one event:

*

* - getPostAnalyzeNodeVisitorClassName

* This method returns a class that is called on every AST node from every

* file being analyzed

*

* A plugin file must

*

* - Contain a class that inherits from \Phan\PluginV3

*

* - End by returning an instance of that class.

*

* It is assumed without being checked that plugins aren't

* mangling state within the passed code base or context.

*

* Note: When adding new plugins,

* add them to the corresponding section of README.md

*/

final class EmptyStatementListPlugin extends PluginV3 implements PostAnalyzeNodeCapability

{

/**

* If true, then never allow empty statement lists, even if there is a TODO/FIXME/"deliberately empty" comment.

* @var bool

* @internal

*/

public static $ignore_todos = false;

public function __construct()

{

self::$ignore_todos = (bool) (Config::getValue('plugin_config')['empty_statement_list_ignore_todos'] ?? false);

}

/**

* @return string - The name of the visitor that will be called.

*/

public static function getPostAnalyzeNodeVisitorClassName(): string

{

return EmptyStatementListVisitor::class;

}

}

/**

* When __invoke on this class is called with a node, a method

* will be dispatched based on the `kind` of the given node.

*

* Visitors such as this are useful for defining lots of different

* checks on a node based on its kind.

*/

final class EmptyStatementListVisitor extends PluginAwarePostAnalysisVisitor

{

/**

* @var list<Node> set by plugin framework

* @suppress PhanReadOnlyProtectedProperty

*/

protected $parent_node_list;

/**

* @param Node $node

* A node to analyze

* @override

*/

public function visitIf(Node $node): void

{

if (isset($node->is_simplified)) {

$first_child = end($node->children);

if (!$first_child instanceof Node || $first_child->children['cond'] === null) {

return;

}

$last_if_elem = reset($node->children);

} else {

$last_if_elem = end($node->children);

}

if (!$last_if_elem instanceof Node) {

// probably impossible

return;

}

$stmts_node = $last_if_elem->children['stmts'];

if (!$stmts_node instanceof Node) {

// probably impossible

return;

}

if ($stmts_node->children) {

// the last if element has statements

return;

}

if ($last_if_elem->children['cond'] === null) {

// Don't bother warning about else

return;

}

if ($this->hasTODOComment($stmts_node->lineno, $node)) {

// Don't warn if there is a FIXME/TODO comment in/around the empty statement list

return;

}

$this->emitPluginIssue(

$this->code_base,

(clone $this->context)->withLineNumberStart($last_if_elem->children['stmts']->lineno ?? $last_if_elem->lineno),

'PhanPluginEmptyStatementIf',

'Empty statement list detected for the last if/elseif statement',

[]

);

}

private function hasTODOComment(int $lineno, Node $analyzed_node, ?int $end_lineno = null): bool

{

if (EmptyStatementListPlugin::$ignore_todos) {

return false;

}

$file = FileCache::getOrReadEntry($this->context->getFile());

$lines = $file->getLines();

$end_lineno = max($lineno, $end_lineno ?? $this->findEndLine($lineno, $analyzed_node));

for ($i = $lineno; $i <= $end_lineno; $i++) {

$line = $lines[$i] ?? null;

if (!is_string($line)) {

break;

}

if (preg_match('/todo|fixme|deliberately empty/i', $line) > 0) {

return true;

}

}

return false;

}

private function findEndLine(int $lineno, Node $search_node): int

{

for ($node_index = count($this->parent_node_list) - 1; $node_index >= 0; $node_index--) {

$node = $this->parent_node_list[$node_index] ?? null;

if (!$node) {

continue;

}

if (isset($node->endLineno)) {

// Return the end line of the function declaration.

return $node->endLineno;

}

if ($node->kind === ast\AST_STMT_LIST) {

foreach ($node->children as $i => $c) {

if ($c === $search_node) {

$next_node = $node->children[$i + 1] ?? null;

if ($next_node instanceof Node) {

return $next_node->lineno - 1;

}

break;

}

}

}

$search_node = $node;

}

// Give up and guess.

return $lineno + 5;

}

/**

* @param Node $node

* A node of kind ast\AST_FOR to analyze

* @override

*/

public function visitFor(Node $node): void

{

$stmts_node = $node->children['stmts'];

if (!$stmts_node instanceof Node) {

// impossible

return;

}

if ($stmts_node->children || ($node->children['loop']->children ?? null)) {

// the for loop has statements, in the body and/or in the loop condition.

return;

}

if ($this->hasTODOComment($stmts_node->lineno, $node)) {

// Don't warn if there is a FIXME/TODO comment in/around the empty statement list

return;

}

$this->emitPluginIssue(

$this->code_base,

(clone $this->context)->withLineNumberStart($stmts_node->lineno ?? $node->lineno),

'PhanPluginEmptyStatementForLoop',

'Empty statement list detected for the for loop',

[]

);

}

/**

* @param Node $node

* A node to analyze

* @override

*/

public function visitWhile(Node $node): void

{

$stmts_node = $node->children['stmts'];

if (!$stmts_node instanceof Node) {

return; // impossible

}

if ($stmts_node->children) {

// the while loop has statements

return;

}

if ($this->hasTODOComment($stmts_node->lineno, $node)) {

// Don't warn if there is a FIXME/TODO comment in/around the empty statement list

return;

}

$this->emitPluginIssue(

$this->code_base,

(clone $this->context)->withLineNumberStart($stmts_node->lineno ?? $node->lineno),

'PhanPluginEmptyStatementWhileLoop',

'Empty statement list detected for the while loop',

[]

);

}

/**

* @param Node $node

* A node to analyze

* @override

*/

public function visitDoWhile(Node $node): void

{

$stmts_node = $node->children['stmts'];

if (!$stmts_node instanceof Node) {

return; // impossible

}

if ($stmts_node->children ?? null) {

// the while loop has statements

return;

}

if ($this->hasTODOComment($stmts_node->lineno, $node)) {

// Don't warn if there is a FIXME/TODO comment in/around the empty statement list

return;

}

$this->emitPluginIssue(

$this->code_base,

(clone $this->context)->withLineNumberStart($stmts_node->lineno),

'PhanPluginEmptyStatementDoWhileLoop',

'Empty statement list detected for the do-while loop',

[]

);

}

/**

* @param Node $node

* A node to analyze

* @override

*/

public function visitForeach(Node $node): void

{

$stmts_node = $node->children['stmts'];

if (!$stmts_node instanceof Node) {

// impossible

return;

}

if ($stmts_node->children) {

// the while loop has statements

return;

}

// Check if the 'as' clause has side effects (assignments to properties/array elements)

if (self::foreachHasSideEffectsInAsClause($node)) {

// Don't warn if foreach assigns to properties/array elements even with empty body

return;

}

if ($this->hasTODOComment($stmts_node->lineno, $node)) {

// Don't warn if there is a FIXME/TODO comment in/around the empty statement list

return;

}

$this->emitPluginIssue(

$this->code_base,

(clone $this->context)->withLineNumberStart($stmts_node->lineno),

'PhanPluginEmptyStatementForeachLoop',

'Empty statement list detected for the foreach loop',

[]

);

}

/**

* Check if a foreach loop has side effects in its 'as' clause.

* Returns true if the value or key are assigned to properties, array elements, etc.

* Array destructuring like [$a, $b] is NOT considered a side effect (assigns to local vars).

*/

private static function foreachHasSideEffectsInAsClause(Node $node): bool

{

// Check the value assignment

$value = $node->children['value'];

if (self::assignmentTargetHasSideEffects($value)) {

return true;

}

// Check the key assignment (if present)

$key = $node->children['key'];

if (self::assignmentTargetHasSideEffects($key)) {

return true;

}

return false;

}

/**

* Check if an assignment target in a foreach has side effects.

* Returns true for property/array element assignments, false for simple variables.

* For array destructuring, recursively checks if any element has side effects.

*/

private static function assignmentTargetHasSideEffects(Node|string|int|float|null $target): bool

{

if (!$target instanceof Node) {

return false;

}

switch ($target->kind) {

case ast\AST_VAR:

case ast\AST_REF:

// Simple variable or reference - no external side effects

return false;

case ast\AST_ARRAY:

case ast\AST_LIST:

// Array destructuring - check if any element has side effects

foreach ($target->children as $elem) {

if (!$elem instanceof Node) {

continue;

}

// AST_ARRAY_ELEM has 'value' child with the actual assignment target

$elem_value = $elem->children['value'] ?? null;

if (self::assignmentTargetHasSideEffects($elem_value)) {

return true;

}

}

return false;

case ast\AST_PROP:

case ast\AST_STATIC_PROP:

case ast\AST_DIM:

// Property or array element assignment - has side effects

return true;

default:

// Other node types - conservatively assume side effects

return true;

}

}

/**

* @param Node $node

* A node to analyze

* @override

*/

public function visitTry(Node $node): void

{

['try' => $try_node, 'finally' => $finally_node] = $node->children;

if (!$try_node->children) {

if (!$this->hasTODOComment($try_node->lineno, $node, $node->children['catches']->children[0]->lineno ?? $finally_node->lineno ?? null)) {

$this->emitPluginIssue(

$this->code_base,

(clone $this->context)->withLineNumberStart($try_node->lineno),

'PhanPluginEmptyStatementTryBody',

'Empty statement list detected for the try statement\'s body',

[]

);

}

} elseif (InferPureAndNoThrowVisitor::isUnlikelyToThrow($this->code_base, $this->context, $try_node)) {

if (!$this->hasTODOComment($try_node->lineno, $node, $node->children['catches']->children[0]->lineno ?? $finally_node->lineno ?? null)) {

$this->emitPluginIssue(

$this->code_base,

(clone $this->context)->withLineNumberStart($try_node->lineno),

'PhanPluginEmptyStatementPossiblyNonThrowingTryBody',

'Found a try block that looks like it might not throw. Note that this check is a heuristic prone to false positives, especially because error handlers, signal handlers, destructors, and other things may all lead to throwing.'

);

}

}

if ($finally_node instanceof Node && !$finally_node->children) {

if (!$this->hasTODOComment($finally_node->lineno, $node)) {

$this->emitPluginIssue(

$this->code_base,

(clone $this->context)->withLineNumberStart($finally_node->lineno),

'PhanPluginEmptyStatementTryFinally',

'Empty statement list detected for the try\'s finally body',

[]

);

}

}

}

/**

* @param Node $node

* A node of kind ast\AST_SWITCH to analyze

* @override

*/

public function visitSwitch(Node $node): void

{

// Check all case statements and return if something that isn't a no-op is seen.

foreach ($node->children['stmts']->children ?? [] as $c) {

if (!$c instanceof Node) {

// impossible

continue;

}

$children = $c->children['stmts']->children ?? null;

if ($children) {

if (count($children) > 1) {

return;

}

$only_node = $children[0];

if ($only_node instanceof Node) {

if (!in_array($only_node->kind, [ast\AST_CONTINUE, ast\AST_BREAK], true)) {

return;

}

if (($only_node->children['depth'] ?? 1) !== 1) {

// not a no-op

return;

}

}

}

if (!ParseVisitor::isConstExpr($c->children['cond'], ParseVisitor::CONSTANT_EXPRESSION_FORBID_NEW_EXPRESSION)) {

return;

}

}

$this->emitPluginIssue(

$this->code_base,

(clone $this->context)->withLineNumberStart($node->lineno),

'PhanPluginEmptyStatementSwitch',

'No side effects seen for any cases of this switch statement',

[]

);

}

}

// Every plugin needs to return an instance of itself at the

// end of the file in which it's defined.

return new EmptyStatementListPlugin();