File: add new File::findExtendedInterfaceNames() utility method

As I've just looked at the `findExtendedClassName()` method again for PR 2127, I remembered that SenseException reported another issue with it a while back via Twitter: https://twitter.com/SenseException/status/997988691468484609.

Summary: interfaces can extend more than one interface (in contrast to classes) and the `findExtendedClassName()` method does not allow for that.
See: http://php.net/manual/en/language.oop5.interfaces.php#example-208

To allow for this from within the existing `findExtendedClassName()` method would change the function signature from `@return string|false` to `@return string|array|false`, thus breaking the API.

So, instead, I've elected to add a new `File::findExtendedInterfaceNames()` method and to recommend using that method for interfaces in the documentation of the `findExtendedClassName()` method .

As the logic needed for these two methods, as well as for the `findImplementedInterfaces()` method, is basically the same, I've extracted the logic out to a private `File::examineObjectDeclarationSignature()` method which is now called by all three functions to DRY out the code.

Includes dedicated unit tests for the new method.

Author: jrfnl

package.xml

@@ -80,6 +80,8 @@ http://pear.php.net/dtd/package-2.0.xsd">
       <file baseinstalldir="" name="FindEndOfStatementTest.php" role="test" />
       <file baseinstalldir="" name="FindExtendedClassNameTest.inc" role="test" />
       <file baseinstalldir="" name="FindExtendedClassNameTest.php" role="test" />
+      <file baseinstalldir="" name="FindExtendedInterfaceNamesTest.inc" role="test" />
+      <file baseinstalldir="" name="FindExtendedInterfaceNamesTest.php" role="test" />
       <file baseinstalldir="" name="FindImplementedInterfaceNamesTest.inc" role="test" />
       <file baseinstalldir="" name="FindImplementedInterfaceNamesTest.php" role="test" />
       <file baseinstalldir="" name="GetMemberPropertiesTest.inc" role="test" />

src/Files/File.php

@@ -2355,109 +2355,153 @@ public function getCondition($stackPtr, $type)
 
     /**
      * Returns the name of the class that the specified class extends.
-     * (works for classes, anonymous classes and interfaces)
+     *
+     * Works for classes, anonymous classes and interfaces, though it is
+     * strongly recommended to use the findExtendedInterfaceNames() method
+     * to examine interfaces as they can extend multiple parent interfaces.
      *
      * Returns FALSE on error or if there is no extended class name.
      *
-     * @param int $stackPtr The stack position of the class.
+     * @param int $stackPtr The stack position of the class keyword.
      *
      * @return string|false
      */
     public function findExtendedClassName($stackPtr)
     {
-        // Check for the existence of the token.
-        if (isset($this->tokens[$stackPtr]) === false) {
-            return false;
-        }
+        $validStructures = [
+            T_CLASS      => true,
+            T_ANON_CLASS => true,
+            T_INTERFACE  => true,
+        ];
 
-        if ($this->tokens[$stackPtr]['code'] !== T_CLASS
-            && $this->tokens[$stackPtr]['code'] !== T_ANON_CLASS
-            && $this->tokens[$stackPtr]['code'] !== T_INTERFACE
-        ) {
-            return false;
-        }
+        $classes = $this->examineObjectDeclarationSignature($stackPtr, $validStructures, T_EXTENDS);
 
-        if (isset($this->tokens[$stackPtr]['scope_opener']) === false) {
+        if (empty($classes) === true) {
             return false;
         }
 
-        $classOpenerIndex = $this->tokens[$stackPtr]['scope_opener'];
-        $extendsIndex     = $this->findNext(T_EXTENDS, $stackPtr, $classOpenerIndex);
-        if (false === $extendsIndex) {
-            return false;
-        }
+        // Classes can only extend one parent class.
+        return $classes[0];
 
-        $find = [
-            T_NS_SEPARATOR,
-            T_STRING,
-            T_WHITESPACE,
-        ];
+    }//end findExtendedClassName()
 
-        $end  = $this->findNext($find, ($extendsIndex + 1), ($classOpenerIndex + 1), true);
-        $name = $this->getTokensAsString(($extendsIndex + 1), ($end - $extendsIndex - 1));
-        $name = trim($name);
 
-        if ($name === '') {
+    /**
+     * Returns the names of the interfaces that the specified interface extends.
+     *
+     * Returns FALSE on error or if there is no extended interface name.
+     *
+     * @param int $stackPtr The stack position of the interface keyword.
+     *
+     * @return array|false
+     */
+    public function findExtendedInterfaceNames($stackPtr)
+    {
+        $validStructures = [T_INTERFACE => true];
+
+        $interfaces = $this->examineObjectDeclarationSignature($stackPtr, $validStructures, T_EXTENDS);
+
+        if (empty($interfaces) === true) {
             return false;
         }
 
-        return $name;
+        return $interfaces;
 
-    }//end findExtendedClassName()
+    }//end findExtendedInterfaceNames()
 
 
     /**
      * Returns the names of the interfaces that the specified class implements.
      *
      * Returns FALSE on error or if there are no implemented interface names.
      *
-     * @param int $stackPtr The stack position of the class.
+     * @param int $stackPtr The stack position of the class keyword.
      *
      * @return array|false
      */
     public function findImplementedInterfaceNames($stackPtr)
+    {
+        $validStructures = [
+            T_CLASS      => true,
+            T_ANON_CLASS => true,
+        ];
+
+        $interfaces = $this->examineObjectDeclarationSignature($stackPtr, $validStructures, T_IMPLEMENTS);
+
+        if (empty($interfaces) === true) {
+            return false;
+        }
+
+        return $interfaces;
+
+    }//end findImplementedInterfaceNames()
+
+
+    /**
+     * Returns the names of the extended classes or interfaces or the implemented
+     * interfaces that the specific class/interface declaration extends/implements.
+     *
+     * Returns FALSE on error or if the object does not extend/implement another
+     * object.
+     *
+     * @param int   $stackPtr The stack position of the class/interface keyword.
+     * @param array $OOTypes  Array of accepted token types.
+     *                        Array format <token constant> => true.
+     * @param int   $keyword  The keyword to examine. Either `T_EXTENDS` or `T_IMPLEMENTS`.
+     *
+     * @return array|false
+     */
+    private function examineObjectDeclarationSignature($stackPtr, $OOTypes, $keyword)
     {
         // Check for the existence of the token.
         if (isset($this->tokens[$stackPtr]) === false) {
             return false;
         }
 
-        if ($this->tokens[$stackPtr]['code'] !== T_CLASS
-            && $this->tokens[$stackPtr]['code'] !== T_ANON_CLASS
-        ) {
+        if (isset($OOTypes[$this->tokens[$stackPtr]['code']]) === false) {
             return false;
         }
 
-        if (isset($this->tokens[$stackPtr]['scope_closer']) === false) {
+        if (isset($this->tokens[$stackPtr]['scope_opener']) === false) {
             return false;
         }
 
-        $classOpenerIndex = $this->tokens[$stackPtr]['scope_opener'];
-        $implementsIndex  = $this->findNext(T_IMPLEMENTS, $stackPtr, $classOpenerIndex);
-        if ($implementsIndex === false) {
+        $openerIndex  = $this->tokens[$stackPtr]['scope_opener'];
+        $keywordIndex = $this->findNext($keyword, ($stackPtr + 1), $openerIndex);
+        if ($keywordIndex === false) {
             return false;
         }
 
-        $find = [
-            T_NS_SEPARATOR,
-            T_STRING,
-            T_WHITESPACE,
-            T_COMMA,
-        ];
+        $find   = Util\Tokens::$emptyTokens;
+        $find[] = T_NS_SEPARATOR;
+        $find[] = T_STRING;
+        $find[] = T_COMMA;
 
-        $end  = $this->findNext($find, ($implementsIndex + 1), ($classOpenerIndex + 1), true);
-        $name = $this->getTokensAsString(($implementsIndex + 1), ($end - $implementsIndex - 1));
-        $name = trim($name);
+        $end   = $this->findNext($find, ($keywordIndex + 1), ($openerIndex + 1), true);
+        $names = [];
+        $name  = '';
+        for ($i = ($keywordIndex + 1); $i < $end; $i++) {
+            if (isset(Util\Tokens::$emptyTokens[$this->tokens[$i]['code']]) === true) {
+                continue;
+            }
 
-        if ($name === '') {
-            return false;
-        } else {
-            $names = explode(',', $name);
-            $names = array_map('trim', $names);
-            return $names;
+            if ($this->tokens[$i]['code'] === T_COMMA && $name !== '') {
+                $names[] = $name;
+                $name    = '';
+                continue;
+            }
+
+            $name .= $this->tokens[$i]['content'];
         }
 
-    }//end findImplementedInterfaceNames()
+        // Add the last name.
+        if ($name !== '') {
+            $names[] = $name;
+        }
+
+        return $names;
+
+    }//end examineObjectDeclarationSignature()
 
 
 }//end class

tests/Core/AllTests.php

@@ -16,6 +16,7 @@
 require_once 'ErrorSuppressionTest.php';
 require_once 'File/FindEndOfStatementTest.php';
 require_once 'File/FindExtendedClassNameTest.php';
+require_once 'File/FindExtendedInterfaceNamesTest.php';
 require_once 'File/FindImplementedInterfaceNamesTest.php';
 require_once 'File/GetMemberPropertiesTest.php';
 require_once 'File/GetMethodParametersTest.php';
@@ -50,6 +51,7 @@ public static function suite()
         $suite->addTestSuite('PHP_CodeSniffer\Tests\Core\ErrorSuppressionTest');
         $suite->addTestSuite('PHP_CodeSniffer\Tests\Core\File\FindEndOfStatementTest');
         $suite->addTestSuite('PHP_CodeSniffer\Tests\Core\File\FindExtendedClassNameTest');
+        $suite->addTestSuite('PHP_CodeSniffer\Tests\Core\File\FindExtendedInterfaceNamesTest');
         $suite->addTestSuite('PHP_CodeSniffer\Tests\Core\File\FindImplementedInterfaceNamesTest');
         $suite->addTestSuite('PHP_CodeSniffer\Tests\Core\File\GetMemberPropertiesTest');
         $suite->addTestSuite('PHP_CodeSniffer\Tests\Core\File\GetMethodParametersTest');

tests/Core/File/FindExtendedInterfaceNamesTest.inc

@@ -0,0 +1,31 @@
+<?php
+/* @codingStandardsIgnoreFile */
+
+namespace PHP_CodeSniffer\Tests\Core\File;
+
+interface testFEINInterface2 {}
+
+/* testInterface */
+interface testFEINInterface {}
+
+/* testExtendedInterface */
+interface testFEINExtendedInterface extends testFEINInterface {}
+
+/* testMultiExtendedInterface */
+interface testFEINMultiExtendedInterface extends testFEINInterface, testFEINInterface2 {}
+
+/* testNamespacedInterface */
+interface testFEINNamespacedInterface extends \PHP_CodeSniffer\Tests\Core\File\testFEINInterface {}
+
+/* testMultiNamespacedInterface */
+interface testFEINMultiNamespacedInterface extends \PHP_CodeSniffer\Tests\Core\File\testFEINInterface, \PHP_CodeSniffer\Tests\Core\File\testFEINInterface2 {}
+
+/* testMultiExtendedInterfaceWithComment */
+interface testFEINMultiExtendedInterface
+	extends
+		/* a comment */
+		testFEINInterface,
+		\PHP_CodeSniffer\Tests /* comment */ \Core \ File \testFEINInterface2,
+		\testFEINInterface3 /* comment */
+{
+}