Source for file FileCommentSniff.php
Documentation is available at FileCommentSniff.php
* Parses and verifies the file doc comment.
* @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\Squiz\Sniffs\Commenting;
use PHP_CodeSniffer\Sniffs\Sniff;
use PHP_CodeSniffer\Files\File;
class FileCommentSniff implements Sniff
* A list of tokenizers this sniff supports.
public $supportedTokenizers = array (
* Returns an array of tokens this test wants to listen for.
public function register ()
return array (T_OPEN_TAG );
* 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.
public function process (File $phpcsFile, $stackPtr)
$this->currentFile = $phpcsFile;
$tokens = $phpcsFile->getTokens ();
$commentStart = $phpcsFile->findNext (T_WHITESPACE , ($stackPtr + 1 ), null , true );
if ($tokens[$commentStart]['code'] === T_COMMENT ) {
$phpcsFile->addError ('You must use "/**" style comments for a file comment', $commentStart, 'WrongStyle');
$phpcsFile->recordMetric ($stackPtr, 'File has doc comment', 'yes');
return ($phpcsFile->numTokens + 1 );
$phpcsFile->addError ('Missing file doc comment', $stackPtr, 'Missing');
$phpcsFile->recordMetric ($stackPtr, 'File has doc comment', 'no');
return ($phpcsFile->numTokens + 1 );
$commentEnd = $tokens[$commentStart]['comment_closer'];
$nextToken = $phpcsFile->findNext (
if (in_array($tokens[$nextToken]['code'], $ignore) === true ) {
$phpcsFile->addError ('Missing file doc comment', $stackPtr, 'Missing');
$phpcsFile->recordMetric ($stackPtr, 'File has doc comment', 'no');
return ($phpcsFile->numTokens + 1 );
$phpcsFile->recordMetric ($stackPtr, 'File has doc comment', 'yes');
// No blank line between the open tag and the file comment.
if ($tokens[$commentStart]['line'] > ($tokens[$stackPtr]['line'] + 1 )) {
$error = 'There must be no blank lines before the file comment';
$phpcsFile->addError ($error, $stackPtr, 'SpacingAfterOpen');
// Exactly one blank line after the file comment.
$next = $phpcsFile->findNext (T_WHITESPACE , ($commentEnd + 1 ), null , true );
if ($tokens[$next]['line'] !== ($tokens[$commentEnd]['line'] + 2 )) {
$error = 'There must be exactly one blank line after the file comment';
$phpcsFile->addError ($error, $commentEnd, 'SpacingAfterComment');
// Required tags in correct order.
foreach ($tokens[$commentStart]['comment_tags'] as $tag) {
$name = $tokens[$tag]['content'];
$isRequired = isset ($required[$name]);
if ($isRequired === true && in_array($name, $foundTags) === true ) {
$error = 'Only one %s tag is allowed in a file comment';
$phpcsFile->addError ($error, $tag, 'Duplicate'. ucfirst(substr($name, 1 )). 'Tag', $data);
if ($isRequired === false ) {
if ($string === false || $tokens[$string]['line'] !== $tokens[$tag]['line']) {
$error = 'Content missing for %s tag in file comment';
$phpcsFile->addError ($error, $tag, 'Empty'. ucfirst(substr($name, 1 )). 'Tag', $data);
if ($name === '@author') {
if ($tokens[$string]['content'] !== 'Squiz Pty Ltd <products@squiz.net>') {
$error = 'Expected "Squiz Pty Ltd <products@squiz.net>" for author tag';
$fix = $phpcsFile->addFixableError ($error, $tag, 'IncorrectAuthor');
$expected = 'Squiz Pty Ltd <products@squiz.net>';
$phpcsFile->fixer ->replaceToken ($string, $expected);
} else if ($name === '@copyright') {
if (preg_match('/^([0-9]{4})(-[0-9]{4})? (Squiz Pty Ltd \(ABN 77 084 670 600\))$/', $tokens[$string]['content']) === 0 ) {
$error = 'Expected "xxxx-xxxx Squiz Pty Ltd (ABN 77 084 670 600)" for copyright declaration';
$fix = $phpcsFile->addFixableError ($error, $tag, 'IncorrectCopyright');
preg_match('/^(([0-9]{4})(-[0-9]{4})?)?.*$/', $tokens[$string]['content'], $matches);
if (isset ($matches[1 ]) === false ) {
$expected = $matches[1 ]. ' Squiz Pty Ltd (ABN 77 084 670 600)';
$phpcsFile->fixer ->replaceToken ($string, $expected);
// Check if the tags are in the correct position.
foreach ($required as $tag => $true) {
if (in_array($tag, $foundTags) === false ) {
$error = 'Missing %s tag in file comment';
$phpcsFile->addError ($error, $commentEnd, 'Missing'. ucfirst(substr($tag, 1 )). 'Tag', $data);
if (isset ($foundTags[$pos]) === false ) {
if ($foundTags[$pos] !== $tag) {
$error = 'The tag in position %s should be the %s tag';
$phpcsFile->addError ($error, $tokens[$commentStart]['comment_tags'][$pos], ucfirst(substr($tag, 1 )). 'TagOrder', $data);
// Ignore the rest of the file.
return ($phpcsFile->numTokens + 1 );
Documentation generated on Mon, 11 Mar 2019 15:27:28 -0400 by phpDocumentor 1.4.4. PEAR Logo Copyright © PHP Group 2004.
|