Document site pass by ref (#71)

Document `sitePassByRefFunctions` option

Author: sirbrillig

README.md

@@ -69,6 +69,7 @@ The available options are as follows:
 - `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'`.
 - `allowUnusedForeachVariables` (bool, default `false`): if set to true, unused keys or values created by the `as` statement in a `foreach` loop will never be marked as unused.
+- `sitePassByRefFunctions` (string, default `null`): a list of custom functions which pass in variables to be initialized by reference (eg `preg_match()`) and therefore should not require those variables to be defined ahead of time. The list is space separated and each entry is of the form `functionName:1,2`. The function name comes first followed by a colon and a comma-separated list of argument numbers (starting from 1) which should be considered variable definitions. The special value `...` in the arguments list will cause all arguments after the last number to be considered variable definitions.
 
 To set these these options, you must use XML in your ruleset. For details, see the [phpcs customizable sniff properties page](https://github.com/squizlabs/PHP_CodeSniffer/wiki/Customisable-Sniff-Properties). Here is an example that ignores all variables that start with an underscore:
 

VariableAnalysis/Sniffs/CodeAnalysis/VariableAnalysisSniff.php

@@ -23,8 +23,12 @@ class VariableAnalysisSniff implements Sniff {
   private $scopes = [];
 
   /**
-   *  Allows an install to extend the list of known pass-by-reference functions
-   *  by defining generic.codeanalysis.variableanalysis.sitePassByRefFunctions.
+   * An associative array of additional pass-by-reference functions. The keys
+   * are the function names, and the values are indexed arrays containing the
+   * argument numbers (starting from 1) of arguments which should be considered
+   * variable definitions. The special value `'...'` in the arguments array
+   * will cause all arguments after the last number to be considered variable
+   * definitions.
    */
   public $sitePassByRefFunctions = null;
 

VariableAnalysis/Tests/CodeAnalysis/VariableAnalysisTest.php

@@ -249,6 +249,33 @@ public function testFunctionWithReferenceWarnings() {
     $phpcsFile = $this->prepareLocalFileForSniffs($this->getSniffFiles(), $fixtureFile);
     $phpcsFile->process();
     $lines = $this->getWarningLineNumbersFromFile($phpcsFile);
+    $expectedWarnings = [
+      8,
+      20,
+      32,
+      33,
+      34,
+      36,
+      37,
+      39,
+      40,
+      46,
+      59,
+      60,
+    ];
+    $this->assertEquals($expectedWarnings, $lines);
+  }
+
+  public function testFunctionWithReferenceWarningsAllowsCustomFunctions() {
+    $fixtureFile = $this->getFixture('FunctionWithReferenceFixture.php');
+    $phpcsFile = $this->prepareLocalFileForSniffs($this->getSniffFiles(), $fixtureFile);
+    $phpcsFile->ruleset->setSniffProperty(
+      'VariableAnalysis\Sniffs\CodeAnalysis\VariableAnalysisSniff',
+      'sitePassByRefFunctions',
+      'my_reference_function:2,3 another_reference_function:2,...'
+    );
+    $phpcsFile->process();
+    $lines = $this->getWarningLineNumbersFromFile($phpcsFile);
     $expectedWarnings = [
       8,
       20,

VariableAnalysis/Tests/CodeAnalysis/fixtures/FunctionWithReferenceFixture.php

@@ -53,3 +53,9 @@ function function_with_pass_by_reference_calls() {
 function function_with_pass_by_ref_assign_only_arg(&$return_value) {
     $return_value = 42;
 }
+
+function function_with_ignored_reference_call() {
+    $foo = 'bar';
+    my_reference_function($foo, $baz, $bip);
+    another_reference_function($foo, $foo2, $foo3);
+}