PSR12.Files.FileHeader now allows a hashbang line at the top of the file (ref #2617)

Author: gsherwood

package.xml

@@ -26,8 +26,8 @@ http://pear.php.net/dtd/package-2.0.xsd">
  </stability>
  <license uri="https://github.com/squizlabs/PHP_CodeSniffer/blob/master/licence.txt">BSD 3-Clause License</license>
  <notes>
-  - PSR12.Files.FileHeader now has better detection of file comments
-    -- No longer ignores comments preceding a use, namespace, or declare statement
+  - PSR12.Files.FileHeader no longer ignores comments preceding a use, namespace, or declare statement
+  - PSR12.Files.FileHeader now allows a hashbang line at the top of the file
   - Fixed bug #2615 : Constant visibility false positive on non-class constants
   - Fixed bug #2616 : PSR12.Files.FileHeader false positive when file only contains docblock
   - Fixed bug #2619 : PSR12.Files.FileHeader locks up when inline comment is the last content in a file
@@ -1066,6 +1066,7 @@ http://pear.php.net/dtd/package-2.0.xsd">
         <file baseinstalldir="PHP/CodeSniffer" name="FileHeaderUnitTest.6.inc" role="test" />
         <file baseinstalldir="PHP/CodeSniffer" name="FileHeaderUnitTest.7.inc" role="test" />
         <file baseinstalldir="PHP/CodeSniffer" name="FileHeaderUnitTest.8.inc" role="test" />
+        <file baseinstalldir="PHP/CodeSniffer" name="FileHeaderUnitTest.9.inc" role="test" />
         <file baseinstalldir="PHP/CodeSniffer" name="FileHeaderUnitTest.php" role="test" />
         <file baseinstalldir="PHP/CodeSniffer" name="ImportStatementUnitTest.inc" role="test" />
         <file baseinstalldir="PHP/CodeSniffer" name="ImportStatementUnitTest.php" role="test" />

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

@@ -302,8 +302,19 @@ public function process(File $phpcsFile, $stackPtr)
         */
 
         if ($stackPtr !== 0) {
-            $error = 'The file header must be the first content in the file';
-            $phpcsFile->addError($error, $stackPtr, 'HeaderPosition');
+            // Allow for hashbang lines.
+            $hashbang = false;
+            if ($tokens[($stackPtr - 1)]['code'] === T_INLINE_HTML) {
+                $content = trim($tokens[($stackPtr - 1)]['content']);
+                if (substr($content, 0, 2) === '#!') {
+                    $hashbang = true;
+                }
+            }
+
+            if ($hashbang === false) {
+                $error = 'The file header must be the first content in the file';
+                $phpcsFile->addError($error, $stackPtr, 'HeaderPosition');
+            }
         }
 
         return $phpcsFile->numTokens;

src/Standards/PSR12/Tests/Files/FileHeaderUnitTest.9.inc

@@ -0,0 +1,7 @@
+#!/usr/bin/env php
+<?php
+
+use Psr\Container\ContainerInterface;
+
+/** @var ContainerInterface $container */
+$container = require __DIR__ . "/../bootstrap.php";