Added PSR12.Files.ImportStatement to enforce the formatting of import statements within a file (ref #750)

Author: gsherwood

package.xml

@@ -69,6 +69,8 @@ http://pear.php.net/dtd/package-2.0.xsd">
     -- Enforce the use of a strict types declaration in PHP files
   - Added PSR12.Files.DeclareStatement sniff
     -- Enforces the formatting of declare statements within a file
+  - Added PSR12.Files.ImportStatement sniff
+    -- Enforces the formatting of import statements within a file
   - Added PSR12.Functions.ReturnTypeDeclaration sniff
     -- Enforces the formatting of return type declarations in functions and closures
   - Added PSR12.Properties.ConstantVisibility sniff
@@ -1109,6 +1111,7 @@ http://pear.php.net/dtd/package-2.0.xsd">
        </dir>
        <dir name="Files">
         <file baseinstalldir="PHP/CodeSniffer" name="DeclareStatementSniff.php" role="php" />
+        <file baseinstalldir="PHP/CodeSniffer" name="ImportStatementSniff.php" role="php" />
        </dir>
        <dir name="Functions">
         <file baseinstalldir="PHP/CodeSniffer" name="NullableTypeDeclarationSniff.php" role="php" />
@@ -1140,6 +1143,8 @@ http://pear.php.net/dtd/package-2.0.xsd">
         <file baseinstalldir="PHP/CodeSniffer" name="DeclareStatementUnitTest.inc" role="test" />
         <file baseinstalldir="PHP/CodeSniffer" name="DeclareStatementUnitTest.inc.fixed" role="test" />
         <file baseinstalldir="PHP/CodeSniffer" name="DeclareStatementUnitTest.php" role="test" />
+        <file baseinstalldir="PHP/CodeSniffer" name="ImportStatementUnitTest.inc" role="test" />
+        <file baseinstalldir="PHP/CodeSniffer" name="ImportStatementUnitTest.php" role="test" />
        </dir>
        <dir name="Functions">
         <file baseinstalldir="PHP/CodeSniffer" name="NullableTypeDeclarationUnitTest.inc" role="test" />

src/Standards/PSR12/Sniffs/Files/ImportStatementSniff.php

@@ -0,0 +1,68 @@
+<?php
+/**
+ * Verifies that import statements are defined correctly.
+ *
+ * @author    Greg Sherwood <gsherwood@squiz.net>
+ * @copyright 2006-2015 Squiz Pty Ltd (ABN 77 084 670 600)
+ * @license   https://github.com/squizlabs/PHP_CodeSniffer/blob/master/licence.txt BSD Licence
+ */
+
+namespace PHP_CodeSniffer\Standards\PSR12\Sniffs\Files;
+
+use PHP_CodeSniffer\Sniffs\Sniff;
+use PHP_CodeSniffer\Files\File;
+use PHP_CodeSniffer\Util\Tokens;
+
+class ImportStatementSniff implements Sniff
+{
+
+
+    /**
+     * Returns an array of tokens this test wants to listen for.
+     *
+     * @return array
+     */
+    public function register()
+    {
+        return [T_USE];
+
+    }//end register()
+
+
+    /**
+     * Processes this test, when one of its tokens is encountered.
+     *
+     * @param \PHP_CodeSniffer\Files\File $phpcsFile The file being scanned.
+     * @param int                         $stackPtr  The position of the current token in the
+     *                                               stack passed in $tokens.
+     *
+     * @return void
+     */
+    public function process(File $phpcsFile, $stackPtr)
+    {
+        $tokens = $phpcsFile->getTokens();
+
+        // Make sure this is not a closure USE group.
+        $next = $phpcsFile->findNext(Tokens::$emptyTokens, ($stackPtr + 1), null, true);
+        if ($tokens[$next]['code'] === T_OPEN_PARENTHESIS) {
+            return;
+        }
+
+        if ($tokens[$next]['code'] === T_STRING
+            && (strtolower($tokens[$next]['content']) === 'function'
+            || strtolower($tokens[$next]['content']) === 'const')
+        ) {
+            $next = $phpcsFile->findNext(Tokens::$emptyTokens, ($next + 1), null, true);
+        }
+
+        if ($tokens[$next]['code'] !== T_NS_SEPARATOR) {
+            return;
+        }
+
+        $error = 'Import statements must not begin with a leading backslash';
+        $phpcsFile->addError($error, $next, 'LeadingSlash');
+
+    }//end process()
+
+
+}//end class

src/Standards/PSR12/Tests/Files/ImportStatementUnitTest.inc

@@ -0,0 +1,19 @@
+<?php
+use \Vendor\Package\{ClassA as A, ClassB, ClassC as C};
+use Vendor\Package\SomeNamespace\ClassD as D;
+use /*comment*/ \Vendor\Package\AnotherNamespace\ClassE as E;
+
+use function Vendor\Package\{functionA, functionB, functionC};
+use FUNCTION \Another\Vendor\functionD;
+
+use CONST Vendor\Package\{CONSTANT_A, CONSTANT_B, CONSTANT_C};
+use const Another\Vendor\CONSTANT_D;
+
+class ClassName3
+{
+    use \FirstTrait;
+    use SecondTrait;
+    use ThirdTrait;
+}
+
+$foo = function() use($bar) {};

src/Standards/PSR12/Tests/Files/ImportStatementUnitTest.php

@@ -0,0 +1,53 @@
+<?php
+/**
+ * Unit test class for the ImportStatement sniff.
+ *
+ * @author    Greg Sherwood <gsherwood@squiz.net>
+ * @copyright 2006-2019 Squiz Pty Ltd (ABN 77 084 670 600)
+ * @license   https://github.com/squizlabs/PHP_CodeSniffer/blob/master/licence.txt BSD Licence
+ */
+
+namespace PHP_CodeSniffer\Standards\PSR12\Tests\Files;
+
+use PHP_CodeSniffer\Tests\Standards\AbstractSniffUnitTest;
+
+class ImportStatementUnitTest extends AbstractSniffUnitTest
+{
+
+
+    /**
+     * Returns the lines where errors should occur.
+     *
+     * The key of the array should represent the line number and the value
+     * should represent the number of errors that should occur on that line.
+     *
+     * @return array<int, int>
+     */
+    public function getErrorList()
+    {
+        return [
+            2  => 1,
+            4  => 1,
+            7  => 1,
+            14 => 1,
+        ];
+
+    }//end getErrorList()
+
+
+    /**
+     * Returns the lines where warnings should occur.
+     *
+     * The key of the array should represent the line number and the value
+     * should represent the number of warnings that should occur on that line.
+     *
+     * @return array<int, int>
+     */
+    public function getWarningList()
+    {
+        return [];
+
+    }//end getWarningList()
+
+
+}//end class

src/Standards/PSR12/ruleset.xml

@@ -101,6 +101,7 @@
     <!-- When the opening php tag is on the first line of the file, it MUST be on its own line with no other statements unless it is a file containing markup outside of PHP opening and closing tags. -->
 
     <!-- Import statements MUST never begin with a leading backslash as they must always be fully qualified. -->
+    <!-- checked by PSR12.Files.ImportStatement -->
 
     <!-- Compound namespaces with a depth of more than two MUST NOT be used. -->
     <!-- checked by PSR12.Namespaces.CompoundNamespaceDepth -->