Add allowUnusedVariablesInFileScope option (#229)

* Add test for allowUnusedVariablesInFileScope

* Add allowUnusedVariablesInFileScope option

* Add allowUnusedVariablesInFileScope to README

Author: sirbrillig

README.md

@@ -65,7 +65,8 @@ The available options are as follows:
 - `allowUnusedCaughtExceptions` (bool, default `true`): if set to true, caught Exception variables will never be marked as unused.
 - `allowUnusedParametersBeforeUsed` (bool, default `true`): if set to true, unused function arguments will be ignored if they are followed by used function arguments.
 - `allowUnusedVariablesBeforeRequire` (bool, default `false`): if set to true, variables defined before a `require`, `require_once`, `include`, or `include_once` will not be marked as unused. They may be intended for the required file.
-- `allowUndefinedVariablesInFileScope` (bool, default `false`): if set to true, undefined variables in the file's top-level scope will never be marked as undefined.
+- `allowUndefinedVariablesInFileScope` (bool, default `false`): if set to true, undefined variables in the file's top-level scope will never be marked as undefined. This can be useful for template files which use many global variables defined elsewhere.
+- `allowUnusedVariablesInFileScope` (bool, default `false`): if set to true, unused variables in the file's top-level scope will never be marked as unused. This can be helpful when defining a lot of global variables to be used elsewhere.
 - `validUnusedVariableNames` (string, default `null`): a space-separated list of names of placeholder variables that you want to ignore from unused variable warnings. For example, to ignore the variables `$junk` and `$unused`, this could be set to `'junk unused'`.
 - `ignoreUnusedRegexp` (string, default `null`): a PHP regexp string (note that this requires explicit delimiters) for variables that you want to ignore from unused variable warnings. For example, to ignore the variables `$_junk` and `$_unused`, this could be set to `'/^_/'`.
 - `validUndefinedVariableNames` (string, default `null`): a space-separated list of names of placeholder variables that you want to ignore from undefined variable warnings. For example, to ignore the variables `$post` and `$undefined`, this could be set to `'post undefined'`. This can be used in combination with `validUndefinedVariableRegexp`.

Tests/VariableAnalysisSniff/GlobalScopeTest.php

@@ -18,6 +18,7 @@ public function testGlobalScopeWarnings() {
       4,
       7,
       10,
+      13,
     ];
     $this->assertEquals($expectedErrors, $lines);
   }
@@ -35,6 +36,24 @@ public function testGlobalScopeWarningsWithAllowUndefinedVariablesInFileScope()
     $expectedErrors = [
       4,
       10,
+      13,
+    ];
+    $this->assertEquals($expectedErrors, $lines);
+  }
+
+  public function testGlobalScopeWarningsWithAllowUnusedVariablesInFileScope() {
+    $fixtureFile = $this->getFixture('GlobalScopeFixture.php');
+    $phpcsFile = $this->prepareLocalFileForSniffs($fixtureFile);
+    $phpcsFile->ruleset->setSniffProperty(
+      'VariableAnalysis\Sniffs\CodeAnalysis\VariableAnalysisSniff',
+      'allowUnusedVariablesInFileScope',
+      'true'
+    );
+    $phpcsFile->process();
+    $lines = $this->getWarningLineNumbersFromFile($phpcsFile);
+    $expectedErrors = [
+      7,
+      10,
     ];
     $this->assertEquals($expectedErrors, $lines);
   }

Tests/VariableAnalysisSniff/fixtures/GlobalScopeFixture.php

@@ -9,3 +9,10 @@
 function thisIsAFunction() {
     echo $whatever; // undefined variable $whatever
 }
+
+$color = 'blue'; // used, but only by a global declaration
+
+function anotherFunction() {
+    global $color;
+    echo $color;
+}

VariableAnalysis/Sniffs/CodeAnalysis/VariableAnalysisSniff.php

@@ -88,6 +88,14 @@ class VariableAnalysisSniff implements Sniff {
    */
   public $allowUndefinedVariablesInFileScope = false;
 
+  /**
+   *  If set, ignores unused variables in the file scope (the top-level
+   *  scope of a file).
+   *
+   *  @var bool
+   */
+  public $allowUnusedVariablesInFileScope = false;
+
   /**
    *  A space-separated list of names of placeholder variables that you want to
    *  ignore from unused variable warnings. For example, to ignore the variables
@@ -1687,6 +1695,9 @@ protected function processScopeCloseForVariable(File $phpcsFile, VariableInfo $v
     if ($this->allowUnusedVariablesBeforeRequire && Helpers::isRequireInScopeAfter($phpcsFile, $varInfo, $scopeInfo)) {
       return;
     }
+    if ($scopeInfo->scopeStartIndex === 0 && $this->allowUnusedVariablesInFileScope) {
+      return;
+    }
 
     $this->warnAboutUnusedVariable($phpcsFile, $varInfo);
   }