Use Exceptions consistently

As far as I can see, Exceptions thrown by sniffs/utility methods when, for instance, a wrong token is passed, should be `RuntimeException`s, while Exceptions thrown by the `Tokenizer` classes should be `TokenizerException`s. In a number of places this was applied inconsistently. This has now been fixed. Aside from that, for quite a number of methods, the `Exception` being thrown has now been documented.
squizlabs · Jan 7, 2019 · 35b8bd7 · 35b8bd7
1 parent dc0b81f
commit 35b8bd7
Show file tree

Hide file tree

Showing 15 changed files with 43 additions and 25 deletions.
diff --git a/src/Config.php b/src/Config.php
@@ -584,6 +584,7 @@ public function restoreDefaults()
      * @param int    $pos The position of the argument on the command line.
      *
      * @return void
+     * @throws \PHP_CodeSniffer\Exceptions\DeepExitException
      */
     public function processShortArgument($arg, $pos)
     {
@@ -688,6 +689,7 @@ public function processShortArgument($arg, $pos)
      * @param int    $pos The position of the argument on the command line.
      *
      * @return void
+     * @throws \PHP_CodeSniffer\Exceptions\DeepExitException
      */
     public function processLongArgument($arg, $pos)
     {
@@ -1249,6 +1251,7 @@ public function processLongArgument($arg, $pos)
      * @param int    $pos The position of the argument on the command line.
      *
      * @return void
+     * @throws \PHP_CodeSniffer\Exceptions\DeepExitException
      */
     public function processUnknownArgument($arg, $pos)
     {
@@ -1274,6 +1277,7 @@ public function processUnknownArgument($arg, $pos)
      * @param string $path The path to the file to add.
      *
      * @return void
+     * @throws \PHP_CodeSniffer\Exceptions\DeepExitException
      */
     public function processFilePath($path)
     {
@@ -1555,7 +1559,7 @@ public static function getExecutablePath($name)
      *
      * @return bool
      * @see    getConfigData()
-     * @throws \PHP_CodeSniffer\Exceptions\RuntimeException If the config file can not be written.
+     * @throws \PHP_CodeSniffer\Exceptions\DeepExitException If the config file can not be written.
      */
     public static function setConfigData($key, $value, $temp=false)
     {
@@ -1636,6 +1640,7 @@ public static function setConfigData($key, $value, $temp=false)
      *
      * @return array<string, string>
      * @see    getConfigData()
+     * @throws \PHP_CodeSniffer\Exceptions\DeepExitException If the config file could not be read.
      */
     public static function getAllConfigData()
     {

diff --git a/src/Files/File.php b/src/Files/File.php
@@ -1291,15 +1291,15 @@ public function getDeclarationName($stackPtr)
      *                      to acquire the parameters for.
      *
      * @return array
-     * @throws \PHP_CodeSniffer\Exceptions\TokenizerException If the specified $stackPtr is not of
-     *                                                        type T_FUNCTION or T_CLOSURE.
+     * @throws \PHP_CodeSniffer\Exceptions\RuntimeException If the specified $stackPtr is not of
+     *                                                      type T_FUNCTION or T_CLOSURE.
      */
     public function getMethodParameters($stackPtr)
     {
         if ($this->tokens[$stackPtr]['code'] !== T_FUNCTION
             && $this->tokens[$stackPtr]['code'] !== T_CLOSURE
         ) {
-            throw new TokenizerException('$stackPtr must be of type T_FUNCTION or T_CLOSURE');
+            throw new RuntimeException('$stackPtr must be of type T_FUNCTION or T_CLOSURE');
         }
 
         $opener = $this->tokens[$stackPtr]['parenthesis_opener'];
@@ -1483,15 +1483,15 @@ public function getMethodParameters($stackPtr)
      *                      acquire the properties for.
      *
      * @return array
-     * @throws \PHP_CodeSniffer\Exceptions\TokenizerException If the specified position is not a
-     *                                                        T_FUNCTION token.
+     * @throws \PHP_CodeSniffer\Exceptions\RuntimeException If the specified position is not a
+     *                                                      T_FUNCTION token.
      */
     public function getMethodProperties($stackPtr)
     {
         if ($this->tokens[$stackPtr]['code'] !== T_FUNCTION
             && $this->tokens[$stackPtr]['code'] !== T_CLOSURE
         ) {
-            throw new TokenizerException('$stackPtr must be of type T_FUNCTION or T_CLOSURE');
+            throw new RuntimeException('$stackPtr must be of type T_FUNCTION or T_CLOSURE');
         }
 
         if ($this->tokens[$stackPtr]['code'] === T_FUNCTION) {
@@ -1632,14 +1632,14 @@ public function getMethodProperties($stackPtr)
      *                      acquire the properties for.
      *
      * @return array
-     * @throws \PHP_CodeSniffer\Exceptions\TokenizerException If the specified position is not a
-     *                                                        T_VARIABLE token, or if the position is not
-     *                                                        a class member variable.
+     * @throws \PHP_CodeSniffer\Exceptions\RuntimeException If the specified position is not a
+     *                                                      T_VARIABLE token, or if the position is not
+     *                                                      a class member variable.
      */
     public function getMemberProperties($stackPtr)
     {
         if ($this->tokens[$stackPtr]['code'] !== T_VARIABLE) {
-            throw new TokenizerException('$stackPtr must be of type T_VARIABLE');
+            throw new RuntimeException('$stackPtr must be of type T_VARIABLE');
         }
 
         $conditions = array_keys($this->tokens[$stackPtr]['conditions']);
@@ -1664,7 +1664,7 @@ public function getMemberProperties($stackPtr)
                     return [];
                 }
             } else {
-                throw new TokenizerException('$stackPtr is not a class member var');
+                throw new RuntimeException('$stackPtr is not a class member var');
             }
         }
 
@@ -1676,7 +1676,7 @@ public function getMemberProperties($stackPtr)
                 && isset($this->tokens[$deepestOpen]['parenthesis_owner']) === true
                 && $this->tokens[$this->tokens[$deepestOpen]['parenthesis_owner']]['code'] === T_FUNCTION
             ) {
-                throw new TokenizerException('$stackPtr is not a class member var');
+                throw new RuntimeException('$stackPtr is not a class member var');
             }
         }
 
@@ -1751,13 +1751,13 @@ public function getMemberProperties($stackPtr)
      *                      acquire the properties for.
      *
      * @return array
-     * @throws \PHP_CodeSniffer\Exceptions\TokenizerException If the specified position is not a
-     *                                                        T_CLASS token.
+     * @throws \PHP_CodeSniffer\Exceptions\RuntimeException If the specified position is not a
+     *                                                      T_CLASS token.
      */
     public function getClassProperties($stackPtr)
     {
         if ($this->tokens[$stackPtr]['code'] !== T_CLASS) {
-            throw new TokenizerException('$stackPtr must be of type T_CLASS');
+            throw new RuntimeException('$stackPtr must be of type T_CLASS');
         }
 
         $valid = [
@@ -1938,6 +1938,7 @@ public function isReference($stackPtr)
      *                          content should be used.
      *
      * @return string The token contents.
+     * @throws \PHP_CodeSniffer\Exceptions\RuntimeException If the specified position does not exist.
      */
     public function getTokensAsString($start, $length, $origContent=false)
     {

diff --git a/src/Files/FileList.php b/src/Files/FileList.php
@@ -136,6 +136,7 @@ public function addFile($path, $file=null)
      * Get the class name of the filter being used for the run.
      *
      * @return string
+     * @throws \PHP_CodeSniffer\Exceptions\DeepExitException If the specified filter could not be found.
      */
     private function getFilterClass()
     {

diff --git a/src/Reporter.php b/src/Reporter.php
@@ -92,7 +92,8 @@ class Reporter
      * @param \PHP_CodeSniffer\Config $config The config data for the run.
      *
      * @return void
-     * @throws \PHP_CodeSniffer\Exceptions\RuntimeException If a report is not available.
+     * @throws \PHP_CodeSniffer\Exceptions\DeepExitException If a custom report class could not be found.
+     * @throws \PHP_CodeSniffer\Exceptions\RuntimeException  If a report class is incorrectly set up.
      */
     public function __construct(Config $config)
     {

diff --git a/src/Reports/Cbf.php b/src/Reports/Cbf.php
@@ -34,6 +34,7 @@ class Cbf implements Report
      * @param int                   $width       Maximum allowed line width.
      *
      * @return bool
+     * @throws \PHP_CodeSniffer\Exceptions\DeepExitException
      */
     public function generateFileReport($report, File $phpcsFile, $showSources=false, $width=80)
     {

diff --git a/src/Reports/Gitblame.php b/src/Reports/Gitblame.php
@@ -63,6 +63,7 @@ protected function getAuthor($line)
      * @param string $filename File to blame.
      *
      * @return array
+     * @throws \PHP_CodeSniffer\Exceptions\DeepExitException
      */
     protected function getBlameContent($filename)
     {

diff --git a/src/Reports/Hgblame.php b/src/Reports/Hgblame.php
@@ -64,6 +64,7 @@ protected function getAuthor($line)
      * @param string $filename File to blame.
      *
      * @return array
+     * @throws \PHP_CodeSniffer\Exceptions\DeepExitException
      */
     protected function getBlameContent($filename)
     {

diff --git a/src/Reports/Svnblame.php b/src/Reports/Svnblame.php
@@ -49,6 +49,7 @@ protected function getAuthor($line)
      * @param string $filename File to blame.
      *
      * @return array
+     * @throws \PHP_CodeSniffer\Exceptions\DeepExitException
      */
     protected function getBlameContent($filename)
     {

diff --git a/src/Ruleset.php b/src/Ruleset.php
@@ -122,6 +122,7 @@ class Ruleset
      * @param \PHP_CodeSniffer\Config $config The config data for the run.
      *
      * @return void
+     * @throws \PHP_CodeSniffer\Exceptions\RuntimeException If no sniffs were registered.
      */
     public function __construct(Config $config)
     {
@@ -305,7 +306,8 @@ public function explain()
      *                            is only used for debug output.
      *
      * @return string[]
-     * @throws \PHP_CodeSniffer\Exceptions\RuntimeException If the ruleset path is invalid.
+     * @throws \PHP_CodeSniffer\Exceptions\RuntimeException - If the ruleset path is invalid.
+     *                                                      - If a specified autoload file could not be found.
      */
     public function processRuleset($rulesetPath, $depth=0)
     {

diff --git a/src/Runner.php b/src/Runner.php
@@ -233,7 +233,7 @@ public function runPHPCBF()
      * Exits if the minimum requirements of PHP_CodSniffer are not met.
      *
      * @return array
-     * @throws \PHP_CodeSniffer\Exceptions\DeepExitException
+     * @throws \PHP_CodeSniffer\Exceptions\DeepExitException If the requirements are not met.
      */
     public function checkRequirements()
     {
@@ -255,7 +255,7 @@ public function checkRequirements()
      * Init the rulesets and other high-level settings.
      *
      * @return void
-     * @throws \PHP_CodeSniffer\Exceptions\DeepExitException
+     * @throws \PHP_CodeSniffer\Exceptions\DeepExitException If a referenced standard is not installed.
      */
     public function init()
     {

diff --git a/src/Sniffs/AbstractScopeSniff.php b/src/Sniffs/AbstractScopeSniff.php
@@ -66,7 +66,8 @@ abstract class AbstractScopeSniff implements Sniff
      *                               processTokenOutsideScope method.
      *
      * @see    PHP_CodeSniffer.getValidScopeTokeners()
-     * @throws \PHP_CodeSniffer\Exceptions\RuntimeException If the specified tokens array is empty.
+     * @throws \PHP_CodeSniffer\Exceptions\RuntimeException If the specified tokens arrays are empty
+     *                                                      or invalid.
      */
     public function __construct(
         array $scopeTokens,

diff --git a/src/Standards/Squiz/Sniffs/Debug/JavaScriptLintSniff.php b/src/Standards/Squiz/Sniffs/Debug/JavaScriptLintSniff.php
@@ -45,6 +45,7 @@ public function register()
      *                                               the token was found.
      *
      * @return void
+     * @throws \PHP_CodeSniffer\Exceptions\RuntimeException If Javascript Lint ran into trouble.
      */
     public function process(File $phpcsFile, $stackPtr)
     {

diff --git a/src/Standards/Zend/Sniffs/Debug/CodeAnalyzerSniff.php b/src/Standards/Zend/Sniffs/Debug/CodeAnalyzerSniff.php
@@ -39,6 +39,7 @@ public function register()
      *                                               the token was found.
      *
      * @return int
+     * @throws \PHP_CodeSniffer\Exceptions\RuntimeException If ZendCodeAnalyzer could not be run.
      */
     public function process(File $phpcsFile, $stackPtr)
     {

diff --git a/src/Tokenizers/Tokenizer.php b/src/Tokenizers/Tokenizer.php
@@ -9,7 +9,7 @@
 
 namespace PHP_CodeSniffer\Tokenizers;
 
-use PHP_CodeSniffer\Exceptions\RuntimeException;
+use PHP_CodeSniffer\Exceptions\TokenizerException;
 use PHP_CodeSniffer\Util;
 
 abstract class Tokenizer
@@ -858,6 +858,7 @@ private function createScopeMap()
      * @param int $ignore   How many curly braces we are ignoring.
      *
      * @return int The position in the stack that closed the scope.
+     * @throws \PHP_CodeSniffer\Exceptions\TokenizerException If the nesting level gets too deep.
      */
     private function recurseScopeMap($stackPtr, $depth=1, &$ignore=0)
     {
@@ -1194,7 +1195,7 @@ private function recurseScopeMap($stackPtr, $depth=1, &$ignore=0)
                             echo '* reached maximum nesting level; aborting *'.PHP_EOL;
                         }
 
-                        throw new RuntimeException('Maximum nesting level reached; file could not be processed');
+                        throw new TokenizerException('Maximum nesting level reached; file could not be processed');
                     }
 
                     $oldDepth = $depth;

diff --git a/tests/Core/File/GetMemberPropertiesTest.php b/tests/Core/File/GetMemberPropertiesTest.php
@@ -327,7 +327,7 @@ public function dataGetMemberProperties()
      *
      * @param string $identifier Comment which preceeds the test case.
      *
-     * @expectedException        PHP_CodeSniffer\Exceptions\TokenizerException
+     * @expectedException        PHP_CodeSniffer\Exceptions\RuntimeException
      * @expectedExceptionMessage $stackPtr is not a class member var
      *
      * @dataProvider dataNotClassProperty
@@ -375,7 +375,7 @@ public function dataNotClassProperty()
     /**
      * Test receiving an expected exception when a non variable is passed.
      *
-     * @expectedException        PHP_CodeSniffer\Exceptions\TokenizerException
+     * @expectedException        PHP_CodeSniffer\Exceptions\RuntimeException
      * @expectedExceptionMessage $stackPtr must be of type T_VARIABLE
      *
      * @return void