Only catch what should be caught

This changes the exceptions being caught in various `catch` statements to more specific ones.

This means that errors which should always have been thrown, will now throw and only the potentially expected (and acceptable) exceptions will now be caught.

Note:
* For the `Namespaces::getDeclaredName()` method, the `catch` has not been changed (other than switching from the PHPCS native `RuntimeException` to the PHPCSUtils one).
    The reason for this is that the method is explicitly documented as returning `false` for non-existent tokens.
    While this behaviour is not in line with other methods in PHPCSUtils, changing the behaviour could be seen as a breaking change, so should be done in a major release.

Includes test for where the behaviour of the functions is now different.

PHPCSUtils/AbstractSniffs/AbstractArrayDeclarationSniff.php

@@ -10,10 +10,11 @@
 
 namespace PHPCSUtils\AbstractSniffs;
 
-use PHP_CodeSniffer\Exceptions\RuntimeException;
 use PHP_CodeSniffer\Files\File;
 use PHP_CodeSniffer\Sniffs\Sniff;
 use PHP_CodeSniffer\Util\Tokens;
+use PHPCSUtils\Exceptions\LogicException;
+use PHPCSUtils\Exceptions\UnexpectedTokenType;
 use PHPCSUtils\Tokens\Collections;
 use PHPCSUtils\Utils\Arrays;
 use PHPCSUtils\Utils\Numbers;
@@ -178,7 +179,7 @@ final public function process(File $phpcsFile, $stackPtr)
     {
         try {
             $this->arrayItems = PassedParameters::getParameters($phpcsFile, $stackPtr);
-        } catch (RuntimeException $e) {
+        } catch (UnexpectedTokenType $e) {
             // Parse error, short list, real square open bracket or incorrectly tokenized short array token.
             return;
         }
@@ -245,7 +246,7 @@ public function processArray(File $phpcsFile)
         foreach ($this->arrayItems as $itemNr => $arrayItem) {
             try {
                 $arrowPtr = Arrays::getDoubleArrowPtr($phpcsFile, $arrayItem['start'], $arrayItem['end']);
-            } catch (RuntimeException $e) {
+            } catch (LogicException $e) {
                 // Parse error: empty array item. Ignore.
                 continue;
             }

PHPCSUtils/Utils/Namespaces.php

@@ -10,11 +10,11 @@
 
 namespace PHPCSUtils\Utils;
 
-use PHP_CodeSniffer\Exceptions\RuntimeException;
 use PHP_CodeSniffer\Files\File;
 use PHP_CodeSniffer\Util\Tokens;
 use PHPCSUtils\BackCompat\BCFile;
 use PHPCSUtils\Exceptions\OutOfBoundsStackPtr;
+use PHPCSUtils\Exceptions\RuntimeException;
 use PHPCSUtils\Exceptions\UnexpectedTokenType;
 use PHPCSUtils\Internal\Cache;
 use PHPCSUtils\Tokens\Collections;

PHPCSUtils/Utils/UseStatements.php

@@ -10,7 +10,6 @@
 
 namespace PHPCSUtils\Utils;
 
-use PHP_CodeSniffer\Exceptions\RuntimeException;
 use PHP_CodeSniffer\Files\File;
 use PHP_CodeSniffer\Util\Tokens;
 use PHPCSUtils\Exceptions\OutOfBoundsStackPtr;
@@ -379,7 +378,7 @@ public static function splitAndMergeImportUseStatement(File $phpcsFile, $stackPt
         try {
             $useStatements         = self::splitImportUseStatement($phpcsFile, $stackPtr);
             $previousUseStatements = self::mergeImportUseStatements($previousUseStatements, $useStatements);
-        } catch (RuntimeException $e) {
+        } catch (ValueError $e) {
             // Not an import use statement.
         }
 

Tests/AbstractSniffs/AbstractArrayDeclaration/AbstractArrayDeclarationSniffTest.php

@@ -40,6 +40,41 @@ final class AbstractArrayDeclarationSniffTest extends PolyfilledTestCase
         'processComma',
     ];
 
+    /**
+     * Test receiving an expected exception when an invalid token pointer is passed.
+     *
+     * @return void
+     */
+    public function testNonExistentToken()
+    {
+        $this->expectException('PHPCSUtils\Exceptions\OutOfBoundsStackPtr');
+        $this->expectExceptionMessage(
+            'Argument #2 ($stackPtr) must be a stack pointer which exists in the $phpcsFile object, 100000 given'
+        );
+
+        $mockObj = $this->getMockedClassUnderTest();
+
+        $mockObj->expects($this->never())
+            ->method('processOpenClose');
+
+        $mockObj->expects($this->never())
+            ->method('processKey');
+
+        $mockObj->expects($this->never())
+            ->method('processNoKey');
+
+        $mockObj->expects($this->never())
+            ->method('processArrow');
+
+        $mockObj->expects($this->never())
+            ->method('processValue');
+
+        $mockObj->expects($this->never())
+            ->method('processComma');
+
+        $mockObj->process(self::$phpcsFile, 100000);
+    }
+
     /**
      * Test that the abstract sniff correctly bows out when presented with a token which is not an array.
      *

Tests/Utils/UseStatements/SplitAndMergeImportUseStatementTest.inc

@@ -1,5 +1,8 @@
 <?php
 
+/* testClosureUse */
+$closure = function() use($bar) {};
+
 /* testUseNamePlainAliased */
 use MyNamespace \ YourClass as ClassAlias;
 

Tests/Utils/UseStatements/SplitAndMergeImportUseStatementTest.php

@@ -10,7 +10,7 @@
 
 namespace PHPCSUtils\Tests\Utils\UseStatements;
 
-use PHPCSUtils\TestUtils\UtilityMethodTestCase;
+use PHPCSUtils\Tests\PolyfilledTestCase;
 use PHPCSUtils\Utils\UseStatements;
 
 /**
@@ -22,9 +22,38 @@
  *
  * @since 1.0.0
  */
-final class SplitAndMergeImportUseStatementTest extends UtilityMethodTestCase
+final class SplitAndMergeImportUseStatementTest extends PolyfilledTestCase
 {
 
+    /**
+     * Test passing a non-existent token pointer.
+     *
+     * @return void
+     */
+    public function testNonExistentToken()
+    {
+        $this->expectException('PHPCSUtils\Exceptions\OutOfBoundsStackPtr');
+        $this->expectExceptionMessage(
+            'Argument #2 ($stackPtr) must be a stack pointer which exists in the $phpcsFile object, 100000 given'
+        );
+
+        UseStatements::splitAndMergeImportUseStatement(self::$phpcsFile, 100000, []);
+    }
+
+    /**
+     * Test receiving an expected exception when a non-supported token is passed.
+     *
+     * @return void
+     */
+    public function testInvalidTokenPassed()
+    {
+        $this->expectException('PHPCSUtils\Exceptions\UnexpectedTokenType');
+        $this->expectExceptionMessage('Argument #2 ($stackPtr) must be of type T_USE;');
+
+        // 0 = PHP open tag.
+        UseStatements::splitAndMergeImportUseStatement(self::$phpcsFile, 0, []);
+    }
+
     /**
      * Test correctly splitting and merging a import `use` statements.
      *
@@ -53,6 +82,15 @@ public function testSplitAndMergeImportUseStatement($testMarker, $expected, $pre
     public static function dataSplitAndMergeImportUseStatement()
     {
         $data = [
+            'closure-use' => [
+                'testMarker' => '/* testClosureUse */',
+                // Same as previous, which, as this is the first test case, is an empty statements array.
+                'expected'   => [
+                    'name'     => [],
+                    'function' => [],
+                    'const'    => [],
+                ],
+            ],
             'name-plain' => [
                 'testMarker' => '/* testUseNamePlainAliased */',
                 'expected'   => [
@@ -118,7 +156,11 @@ public static function dataSplitAndMergeImportUseStatement()
             ],
         ];
 
-        $previousUse = [];
+        $previousUse = [
+            'name'     => [],
+            'function' => [],
+            'const'    => [],
+        ];
         foreach ($data as $key => $value) {
             $data[$key]['previousUse'] = $previousUse;
             $previousUse               = $value['expected'];