From c1077f32d3cb0b4ee081eeabe740673a5dc2fc81 Mon Sep 17 00:00:00 2001
From: AndrolGenhald <AndrolGenhald@gmail.com>
Date: Fri, 18 Feb 2022 11:36:25 -0600
Subject: [PATCH] Improve documentation for InvalidGlobal to explain that it's
 sometimes valid.

---
 docs/running_psalm/issues/InvalidGlobal.md                | 6 +++++-
 src/Psalm/Internal/Analyzer/Statements/GlobalAnalyzer.php | 2 +-
 2 files changed, 6 insertions(+), 2 deletions(-)

diff --git a/docs/running_psalm/issues/InvalidGlobal.md b/docs/running_psalm/issues/InvalidGlobal.md
index b5a8999322d..bbc8e9b296e 100644
--- a/docs/running_psalm/issues/InvalidGlobal.md
+++ b/docs/running_psalm/issues/InvalidGlobal.md
@@ -1,9 +1,13 @@
 # InvalidGlobal
 
-Emitted when there's a reference to the global keyword where it's not expected
+Emitted when there's a reference to the global keyword where it's not expected.
 
 ```php
 <?php
 
 global $e;
 ```
+
+If the file is included from a non-global scope this issue will have to be suppressed. See
+[Config suppression](../dealing_with_code_issues/#suppressing-issues) for how to suppress this at the file or directory
+level.
diff --git a/src/Psalm/Internal/Analyzer/Statements/GlobalAnalyzer.php b/src/Psalm/Internal/Analyzer/Statements/GlobalAnalyzer.php
index a04e72d9740..9b7624ee394 100644
--- a/src/Psalm/Internal/Analyzer/Statements/GlobalAnalyzer.php
+++ b/src/Psalm/Internal/Analyzer/Statements/GlobalAnalyzer.php
@@ -30,7 +30,7 @@ public static function analyze(
         if (!$context->collect_initializations && !$global_context) {
             IssueBuffer::maybeAdd(
                 new InvalidGlobal(
-                    'Cannot use global scope here',
+                    'Cannot use global scope here (unless this file is included from a non-global scope)',
                     new CodeLocation($statements_analyzer, $stmt)
                 ),
                 $statements_analyzer->getSource()->getSuppressedIssues()