Made respecting require/include once calls optional

Author: mmcev106

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

@@ -175,10 +175,15 @@ public static function analyze(
                         $statements_analyzer->hasAlreadyRequiredFilePath($path_to_file)
                         && (
                             !$codebase->file_storage_provider->get($path_to_file)->has_extra_statements
-                            || in_array($stmt->type, [
-                                PhpParser\Node\Expr\Include_::TYPE_INCLUDE_ONCE,
-                                PhpParser\Node\Expr\Include_::TYPE_REQUIRE_ONCE,
-                            ])
+                            ||
+                            (
+                                $config->respect_include_once
+                                &&
+                                in_array($stmt->type, [
+                                    PhpParser\Node\Expr\Include_::TYPE_INCLUDE_ONCE,
+                                    PhpParser\Node\Expr\Include_::TYPE_REQUIRE_ONCE,
+                                ])
+                            )
                         )
                     )
                 ) {