Throw tag sniff supporting re-thrown exceptions

CodeSniffer/Standards/Squiz/Sniffs/Commenting/FunctionCommentThrowTagSniff.php

@@ -97,8 +97,15 @@ protected function processTokenWithinScope(PHP_CodeSniffer_File $phpcsFile, $sta
  while ($currPos < $currScopeEnd && $currPos !== false) {
  /*
  If we can't find a NEW, we are probably throwing
- a variable, so we ignore it, but they still need to
- provide at least one @throws tag, even through we
+ a variable.
+
+ If we're throwing the same variable as the exception container
+ from the nearest 'catch' block, we take that exception, as it is
+ likely to be a re-throw.
+
+ If we can't find a matching catch block, or the variable name
+ is different, it's probably a different variable, so we ignore it,
+ but they still need to provide at least one @throws tag, even through we
  don't know the exception class.
  */
 
@@ -135,6 +142,60 @@ protected function processTokenWithinScope(PHP_CodeSniffer_File $phpcsFile, $sta
  $throwTokens[] = $phpcsFile->getTokensAsString($currException, ($endException - $currException));
  }
  }//end if
+ } else if ($tokens[$nextToken]['code'] === T_VARIABLE) {
+ // Find where the nearest 'catch' block in this scope.
+ $catch = $phpcsFile->findPrevious(
+ T_CATCH,
+ $currPos,
+ $tokens[$currScope]['scope_opener'],
+ false,
+ null,
+ false
+ );
+
+ if ($catch !== false) {
+ // Get the start of the 'catch' exception.
+ $currException = $phpcsFile->findNext(
+ array(
+ T_NS_SEPARATOR,
+ T_STRING,
+ ),
+ $tokens[$catch]['parenthesis_opener'],
+ $tokens[$catch]['parenthesis_closer'],
+ false,
+ null,
+ true
+ );
+
+ if ($currException !== false) {
+ // Find the next whitespace (which should be the end of the exception).
+ $endException = $phpcsFile->findNext(
+ T_WHITESPACE,
+ ($currException + 1),
+ $tokens[$catch]['parenthesis_closer'],
+ false,
+ null,
+ true
+ );
+
+ if ($endException !== false) {
+ // Find the variable that we're catching into.
+ $thrownVar = $phpcsFile->findNext(
+ T_VARIABLE,
+ ($endException + 1),
+ $tokens[$catch]["parenthesis_closer"],
+ false,
+ null,
+ true
+ );
+
+ // Sanity check that the variable that the exception is caught into is the one that's thrown.
+ if ($tokens[$thrownVar]['content'] === $tokens[$nextToken]['content']) {
+ $throwTokens[] = $phpcsFile->getTokensAsString($currException, ($endException - $currException));
+ }//end if
+ }//end if
+ }//end if
+ }//end if
  }//end if
 
  $currPos = $phpcsFile->findNext(T_THROW, ($currPos + 1), $currScopeEnd);

CodeSniffer/Standards/Squiz/Tests/Commenting/FunctionCommentThrowTagUnitTest.inc

@@ -192,7 +192,43 @@ class FunctionCommentThrowTagUnitTest
 
  }//end okFunction
 
+ /**
+ * Needs at throws tag for rethrown exception,
+ * even though we have one throws tag.
+ *
+ * @throws PHP_Exception1
+ */
+ public function notOkVariableRethrown()
+ {
+ throw new PHP_Exception1('Error');
+
+ try {
+ // Do something.
+ } catch (PHP_Exception2 $e) {
+ logError();
+ throw $e;
+ }
+
+ }//end notOkVariableRethrown()
+
+ /**
+ * Has correct throws tags for all exceptions
+ *
+ * @throws PHP_Exception1
+ * @throws PHP_Exception2
+ */
+ public function okVariableRethrown()
+ {
+ throw new PHP_Exception1('Error');
+
+ try {
+ // Do something.
+ } catch (PHP_Exception2 $e) {
+ logError();
+ throw $e;
+ }
 
+ }//end okVariableRethrown()
 }//end class
 
 class NamespacedException {

CodeSniffer/Standards/Squiz/Tests/Commenting/FunctionCommentThrowTagUnitTest.php

@@ -54,7 +54,8 @@ public function getErrorList()
  61 => 2,
  106 => 1,
  123 => 1,
- 215 => 1,
+ 200 => 1,
+ 251 => 1,
  );
 
  }//end getErrorList()