[FEATURE] Introduce BeforeStatementAnalysisEvent

docs/running_psalm/plugins/authoring_plugins.md

@@ -80,6 +80,7 @@ class SomePlugin implements \Psalm\Plugin\EventHandler\AfterStatementAnalysisInt
 - `AfterFunctionCallAnalysisInterface` - called after Psalm evaluates a function call to any function defined within the project itself. Can alter the return type or perform modifications of the call.
 - `AfterFunctionLikeAnalysisInterface` - called after Psalm has completed its analysis of a given function-like.
 - `AfterMethodCallAnalysisInterface` - called after Psalm analyzes a method call.
+- `BeforeStatementAnalysisInterface` - called before Psalm evaluates an statement.
 - `AfterStatementAnalysisInterface` - called after Psalm evaluates an statement.
 - `BeforeFileAnalysisInterface` - called before Psalm analyzes a file.
 - `FunctionExistenceProviderInterface` - can be used to override Psalm's builtin function existence checks for one or more functions.

src/Psalm/Internal/Analyzer/StatementsAnalyzer.php

@@ -56,6 +56,7 @@
 use Psalm\IssueBuffer;
 use Psalm\NodeTypeProvider;
 use Psalm\Plugin\EventHandler\Event\AfterStatementAnalysisEvent;
+use Psalm\Plugin\EventHandler\Event\BeforeStatementAnalysisEvent;
 use Psalm\Type;
 use UnexpectedValueException;
 
@@ -353,6 +354,10 @@ private static function analyzeStatement(
         Context $context,
         ?Context $global_context
     ): ?bool {
+        if (self::dispatchBeforeStatementAnalysis($stmt, $context, $statements_analyzer) === false) {
+            return false;
+        }
+
         $ignore_variable_property = false;
         $ignore_variable_method = false;
 
@@ -619,25 +624,10 @@ private static function analyzeStatement(
             }
         }
 
-        $codebase = $statements_analyzer->getCodebase();
-
-        $event = new AfterStatementAnalysisEvent(
-            $stmt,
-            $context,
-            $statements_analyzer,
-            $codebase,
-            []
-        );
-
-        if ($codebase->config->eventDispatcher->dispatchAfterStatementAnalysis($event) === false) {
+        if (self::dispatchAfterStatementAnalysis($stmt, $context, $statements_analyzer) === false) {
             return false;
         }
 
-        $file_manipulations = $event->getFileReplacements();
-        if ($file_manipulations) {
-            FileManipulationBuffer::add($statements_analyzer->getFilePath(), $file_manipulations);
-        }
-
         if ($new_issues) {
             $statements_analyzer->removeSuppressedIssues($new_issues);
         }
@@ -673,6 +663,58 @@ private static function analyzeStatement(
         return null;
     }
 
+    private static function dispatchAfterStatementAnalysis(
+        PhpParser\Node\Stmt $stmt,
+        Context $context,
+        StatementsAnalyzer $statements_analyzer
+    ): ?bool {
+        $codebase = $statements_analyzer->getCodebase();
+
+        $event = new AfterStatementAnalysisEvent(
+            $stmt,
+            $context,
+            $statements_analyzer,
+            $codebase,
+            []
+        );
+
+        if ($codebase->config->eventDispatcher->dispatchAfterStatementAnalysis($event) === false) {
+            return false;
+        }
+
+        $file_manipulations = $event->getFileReplacements();
+        if ($file_manipulations) {
+            FileManipulationBuffer::add($statements_analyzer->getFilePath(), $file_manipulations);
+        }
+        return null;
+    }
+
+    private static function dispatchBeforeStatementAnalysis(
+        PhpParser\Node\Stmt $stmt,
+        Context $context,
+        StatementsAnalyzer $statements_analyzer
+    ): ?bool {
+        $codebase = $statements_analyzer->getCodebase();
+
+        $event = new BeforeStatementAnalysisEvent(
+            $stmt,
+            $context,
+            $statements_analyzer,
+            $codebase,
+            []
+        );
+
+        if ($codebase->config->eventDispatcher->dispatchBeforeStatementAnalysis($event) === false) {
+            return false;
+        }
+
+        $file_manipulations = $event->getFileReplacements();
+        if ($file_manipulations) {
+            FileManipulationBuffer::add($statements_analyzer->getFilePath(), $file_manipulations);
+        }
+        return null;
+    }
+
     private function parseStatementDocblock(
         PhpParser\Comment\Doc $docblock,
         PhpParser\Node\Stmt $stmt,

src/Psalm/Internal/EventDispatcher.php

@@ -16,6 +16,7 @@
 use Psalm\Plugin\EventHandler\AfterMethodCallAnalysisInterface;
 use Psalm\Plugin\EventHandler\AfterStatementAnalysisInterface;
 use Psalm\Plugin\EventHandler\BeforeFileAnalysisInterface;
+use Psalm\Plugin\EventHandler\BeforeStatementAnalysisInterface;
 use Psalm\Plugin\EventHandler\Event\AddRemoveTaintsEvent;
 use Psalm\Plugin\EventHandler\Event\AfterAnalysisEvent;
 use Psalm\Plugin\EventHandler\Event\AfterClassLikeAnalysisEvent;
@@ -30,6 +31,7 @@
 use Psalm\Plugin\EventHandler\Event\AfterMethodCallAnalysisEvent;
 use Psalm\Plugin\EventHandler\Event\AfterStatementAnalysisEvent;
 use Psalm\Plugin\EventHandler\Event\BeforeFileAnalysisEvent;
+use Psalm\Plugin\EventHandler\Event\BeforeStatementAnalysisEvent;
 use Psalm\Plugin\EventHandler\Event\StringInterpreterEvent;
 use Psalm\Plugin\EventHandler\RemoveTaintsInterface;
 use Psalm\Plugin\EventHandler\StringInterpreterInterface;
@@ -80,6 +82,13 @@ class EventDispatcher
      */
     public $after_expression_checks = [];
 
+    /**
+     * Static methods to be called before statement checks are processed
+     *
+     * @var list<class-string<BeforeStatementAnalysisInterface>>
+     */
+    public $before_statement_checks = [];
+
     /**
      * Static methods to be called after statement checks have completed
      *
@@ -185,6 +194,10 @@ public function registerClass(string $class): void
             $this->after_expression_checks[] = $class;
         }
 
+        if (is_subclass_of($class, BeforeStatementAnalysisInterface::class)) {
+            $this->before_statement_checks[] = $class;
+        }
+
         if (is_subclass_of($class, AfterStatementAnalysisInterface::class)) {
             $this->after_statement_checks[] = $class;
         }
@@ -271,6 +284,16 @@ public function dispatchAfterExpressionAnalysis(AfterExpressionAnalysisEvent $ev
         return null;
     }
 
+    public function dispatchBeforeStatementAnalysis(BeforeStatementAnalysisEvent $event): ?bool
+    {
+        foreach ($this->before_statement_checks as $handler) {
+            if ($handler::beforeStatementAnalysis($event) === false) {
+                return false;
+            }
+        }
+        return null;
+    }
+
     public function dispatchAfterStatementAnalysis(AfterStatementAnalysisEvent $event): ?bool
     {
         foreach ($this->after_statement_checks as $handler) {

src/Psalm/Plugin/EventHandler/BeforeStatementAnalysisInterface.php

@@ -0,0 +1,19 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Psalm\Plugin\EventHandler;
+
+use Psalm\Plugin\EventHandler\Event\BeforeStatementAnalysisEvent;
+
+interface BeforeStatementAnalysisInterface
+{
+    /**
+     * Called before a statement has been checked
+     *
+     * @return null|false Whether to continue
+     *  + `null` continues with next event handler
+     *  + `false` stops analyzing current statement in StatementsAnalyzer
+     */
+    public static function beforeStatementAnalysis(BeforeStatementAnalysisEvent $event): ?bool;
+}

src/Psalm/Plugin/EventHandler/Event/BeforeStatementAnalysisEvent.php

@@ -0,0 +1,83 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Psalm\Plugin\EventHandler\Event;
+
+use PhpParser\Node\Stmt;
+use Psalm\Codebase;
+use Psalm\Context;
+use Psalm\FileManipulation;
+use Psalm\StatementsSource;
+
+final class BeforeStatementAnalysisEvent
+{
+    private Stmt $stmt;
+    private Context $context;
+    private StatementsSource $statements_source;
+    private Codebase $codebase;
+    /**
+     * @var list<FileManipulation>
+     */
+    private array $file_replacements;
+
+    /**
+     * Called after a statement has been checked
+     *
+     * @param list<FileManipulation> $file_replacements
+     */
+    public function __construct(
+        Stmt $stmt,
+        Context $context,
+        StatementsSource $statements_source,
+        Codebase $codebase,
+        array $file_replacements = []
+    ) {
+        $this->stmt = $stmt;
+        $this->context = $context;
+        $this->statements_source = $statements_source;
+        $this->codebase = $codebase;
+        $this->file_replacements = $file_replacements;
+    }
+
+    public function getStmt(): Stmt
+    {
+        return $this->stmt;
+    }
+
+    public function setStmt(Stmt $stmt): void
+    {
+        $this->stmt = $stmt;
+    }
+
+    public function getContext(): Context
+    {
+        return $this->context;
+    }
+
+    public function getStatementsSource(): StatementsSource
+    {
+        return $this->statements_source;
+    }
+
+    public function getCodebase(): Codebase
+    {
+        return $this->codebase;
+    }
+
+    /**
+     * @return list<FileManipulation>
+     */
+    public function getFileReplacements(): array
+    {
+        return $this->file_replacements;
+    }
+
+    /**
+     * @param list<FileManipulation> $file_replacements
+     */
+    public function setFileReplacements(array $file_replacements): void
+    {
+        $this->file_replacements = $file_replacements;
+    }
+}