PSR12.Files.FileHeader misidentifies file header in mixed content file

[okainov]

Describe the bug

I'm getting 2 | ERROR | The file header must be the first content in the file (PSR12.Files.FileHeader.HeaderPosition) when <?php is in the middle of a mixed file when followed by docstring-like comment.

Code sample

<div></div>
<?php

/*** Comment - this is important, only comment in such format triggers the issue ***/

$b = 3;

Custom ruleset

N/A

To reproduce

Steps to reproduce the behavior:

1. Create a file called test.php with the code sample above...
2. Run phpcs -s --standard=PSR12 test.php
3. See error message displayed

FOUND 1 ERROR AFFECTING 1 LINE
-----------------------------------------------------------------------------------------------------------
 2 | ERROR | The file header must be the first content in the file (PSR12.Files.FileHeader.HeaderPosition)

Expected behavior

No error expected in this case

Versions (please complete the following information)

Operating System	Windows, Docker
PHP version	7.4
PHP_CodeSniffer version	PHP_CodeSniffer version 3.13.2 (stable) , 4.0.1 (stable)
Standard	PSR12
Install type	Composer in docker container

Additional context

Add any other context about the problem here.

Please confirm

• I have searched the issue list and am not opening a duplicate issue.
• I have read the Contribution Guidelines and this is not a support question.
• I confirm that this bug is a bug in PHP_CodeSniffer and not in one of the external standards.
• I have verified the issue still exists in the 4.x branch of PHP_CodeSniffer.

See also squizlabs/PHP_CodeSniffer#2732

[jrfnl]

✅ Confirmed as reproducable.
Solution to be determined.

Similar issues:

• PSR12.Files.FileHeader.SpacingAfterBlock error on declare strict types in files containing markup outside PHP opening and closing tags squizlabs/PHP_CodeSniffer#2911
• PSR12.Files.FileHeader false positive for file with mixed PHP and HTML and no file header squizlabs/PHP_CodeSniffer#2848
• PSR12.Files.FileHeader misidentifies file header in mixed content file squizlabs/PHP_CodeSniffer#2732

Other related issues:

• PSR12.Files.FileHeader not an accurate definition of the file header squizlabs/PHP_CodeSniffer#3596
• PSR12.Files.FileHeader: false positive when there is no header #21 ( PSR12.Files.FileHeader: false positive when there is no header squizlabs/PHP_CodeSniffer#2997 )

I believe the sniff may need a careful review to verify it correctly complies with the following rule from PSR12:

When a file contains a mix of HTML and PHP, any of the above sections may still be used. If so, they MUST be present at the top of the file, even if the remainder of the code consists of a closing PHP tag and then a mixture of HTML and PHP.