Improve performance by avoiding repeated scanning of files included/required only once

config.xsd

@@ -40,6 +40,7 @@
         <xs:attribute name="addParamDefaultToDocblockType" type="xs:boolean" default="false" />
         <xs:attribute name="allowFileIncludes" type="xs:boolean" default="true" />
         <xs:attribute name="ignoreIncludeSideEffects" type="xs:boolean" default="false" />
+        <xs:attribute name="respectIncludeOnce" type="xs:boolean" default="false" />
         <xs:attribute name="allowStringToStandInForClass" type="xs:boolean" default="false" />
         <xs:attribute name="checkForThrowsDocblock" type="xs:boolean" default="false" />
         <xs:attribute name="checkForThrowsInGlobalScope" type="xs:boolean" default="false" />

docs/running_psalm/configuration.md

@@ -489,6 +489,18 @@ Ignoring include side effects can significantly speed up scans on legacy codebas
 
 Defaults to `false`.
 
+#### respectIncludeOnce
+```xml
+<psalm
+  respectIncludeOnce="[bool]"
+>
+```
+Whether or not to process files after the first `require_once()` or `include_once()` call.  
+
+By default, Psalm treats `require_once()` and `include_once()` calls as if they were `require()` or `include()` calls in an attempt to consider all possible permutations of file include order.  Respecting `require_once()` and `include_once()` behavior can significantly speed up scans on codebases with circular `require_once()` or `include_once()` calls.  While potentially less comprehensive, this setting aims to more closely mimic PHP's runtime behavior.
+
+Defaults to `false`.
+
 #### serializer
 ```xml
 <psalm

src/Psalm/Config.php

@@ -304,6 +304,8 @@ final class Config
 
     public bool $ignore_include_side_effects = false;
 
+    public bool $respect_include_once = false;
+
     /** @var 1|2|3|4|5|6|7|8 */
     public int $level = 1;
 
@@ -954,6 +956,7 @@ private static function fromXmlAndPaths(
             'resolveFromConfigFile' => 'resolve_from_config_file',
             'allowFileIncludes' => 'allow_includes',
             'ignoreIncludeSideEffects' => 'ignore_include_side_effects',
+            'respectIncludeOnce' => 'respect_include_once',
             'strictBinaryOperands' => 'strict_binary_operands',
             'allowBoolToLiteralBoolComparison' => 'allow_bool_to_literal_bool_comparison',
             'rememberPropertyAssignmentsAfterCall' => 'remember_property_assignments_after_call',

src/Psalm/Internal/Analyzer/Statements/Expression/IncludeAnalyzer.php

@@ -171,8 +171,21 @@ public static function analyze(
                 }
                 if ($statements_analyzer->hasParentFilePath($path_to_file)
                     || !$codebase->file_storage_provider->has($path_to_file)
-                    || ($statements_analyzer->hasAlreadyRequiredFilePath($path_to_file)
-                        && !$codebase->file_storage_provider->get($path_to_file)->has_extra_statements)
+                    || (
+                        $statements_analyzer->hasAlreadyRequiredFilePath($path_to_file)
+                        && (
+                            !$codebase->file_storage_provider->get($path_to_file)->has_extra_statements
+                            ||
+                            (
+                                $config->respect_include_once
+                                &&
+                                in_array($stmt->type, [
+                                    PhpParser\Node\Expr\Include_::TYPE_INCLUDE_ONCE,
+                                    PhpParser\Node\Expr\Include_::TYPE_REQUIRE_ONCE,
+                                ])
+                            )
+                        )
+                    )
                 ) {
                     return true;
                 }