Chris@0: <?php
Chris@0: /**
Chris@0:  * Parses and verifies class property doc comments.
Chris@0:  *
Chris@0:  * @category PHP
Chris@0:  * @package  PHP_CodeSniffer
Chris@0:  * @link     http://pear.php.net/package/PHP_CodeSniffer
Chris@0:  */
Chris@0: 
Chris@17: namespace Drupal\Sniffs\Commenting;
Chris@17: 
Chris@17: use Drupal\Sniffs\Commenting\FunctionCommentSniff;
Chris@17: use PHP_CodeSniffer\Files\File;
Chris@17: use PHP_CodeSniffer\Sniffs\AbstractVariableSniff;
Chris@17: use PHP_CodeSniffer\Util\Tokens;
Chris@17: 
Chris@0: /**
Chris@0:  * Parses and verifies class property doc comments.
Chris@0:  *
Chris@17:  * Laregely copied from
Chris@17:  * \PHP_CodeSniffer\Standards\Squiz\Sniffs\Commenting\VariableCommentSniff.
Chris@0:  *
Chris@0:  * @category PHP
Chris@0:  * @package  PHP_CodeSniffer
Chris@0:  * @link     http://pear.php.net/package/PHP_CodeSniffer
Chris@0:  */
Chris@17: class VariableCommentSniff extends AbstractVariableSniff
Chris@0: {
Chris@0: 
Chris@0: 
Chris@0:     /**
Chris@0:      * Called to process class member vars.
Chris@0:      *
Chris@17:      * @param \PHP_CodeSniffer\Files\File $phpcsFile The file being scanned.
Chris@17:      * @param int                         $stackPtr  The position of the current token
Chris@17:      *                                               in the stack passed in $tokens.
Chris@0:      *
Chris@0:      * @return void
Chris@0:      */
Chris@17:     public function processMemberVar(File $phpcsFile, $stackPtr)
Chris@0:     {
Chris@0:         $tokens       = $phpcsFile->getTokens();
Chris@0:         $commentToken = array(
Chris@0:                          T_COMMENT,
Chris@0:                          T_DOC_COMMENT_CLOSE_TAG,
Chris@0:                         );
Chris@0: 
Chris@0:         $commentEnd = $phpcsFile->findPrevious($commentToken, $stackPtr);
Chris@0:         if ($commentEnd === false) {
Chris@0:             return;
Chris@0:         }
Chris@0: 
Chris@0:         if ($tokens[$commentEnd]['code'] === T_COMMENT) {
Chris@0:             $fix = $phpcsFile->addFixableError('You must use "/**" style comments for a member variable comment', $stackPtr, 'WrongStyle');
Chris@0:             if ($fix === true) {
Chris@0:                 // Convert the comment into a doc comment.
Chris@0:                 $phpcsFile->fixer->beginChangeset();
Chris@0:                 $comment = '';
Chris@0:                 for ($i = $commentEnd; $tokens[$i]['code'] === T_COMMENT; $i--) {
Chris@0:                     $comment = ' *'.ltrim($tokens[$i]['content'], '/* ').$comment;
Chris@0:                     $phpcsFile->fixer->replaceToken($i, '');
Chris@0:                 }
Chris@0: 
Chris@0:                 $phpcsFile->fixer->replaceToken($commentEnd, "/**\n".rtrim($comment, "*/\n")."\n */\n");
Chris@0:                 $phpcsFile->fixer->endChangeset();
Chris@0:             }
Chris@0: 
Chris@0:             return;
Chris@0:         } else if ($tokens[$commentEnd]['code'] !== T_DOC_COMMENT_CLOSE_TAG) {
Chris@0:             return;
Chris@0:         } else {
Chris@0:             // Make sure the comment we have found belongs to us.
Chris@0:             $commentFor = $phpcsFile->findNext(array(T_VARIABLE, T_CLASS, T_INTERFACE), ($commentEnd + 1));
Chris@0:             if ($commentFor !== $stackPtr) {
Chris@0:                 return;
Chris@0:             }
Chris@0:         }//end if
Chris@0: 
Chris@0:         $commentStart = $tokens[$commentEnd]['comment_opener'];
Chris@0: 
Chris@0:         $commentContent = $phpcsFile->getTokensAsString($commentStart, ($commentEnd - $commentStart));
Chris@0:         if (strpos($commentContent, '{@inheritdoc}') !== false) {
Chris@0:             return;
Chris@0:         }
Chris@0: 
Chris@0:         $foundVar = null;
Chris@0:         foreach ($tokens[$commentStart]['comment_tags'] as $tag) {
Chris@0:             if ($tokens[$tag]['content'] === '@var') {
Chris@0:                 if ($foundVar !== null) {
Chris@0:                     $error = 'Only one @var tag is allowed in a member variable comment';
Chris@0:                     $phpcsFile->addError($error, $tag, 'DuplicateVar');
Chris@0:                 } else {
Chris@0:                     $foundVar = $tag;
Chris@0:                 }
Chris@0:             } else if ($tokens[$tag]['content'] === '@see') {
Chris@0:                 // Make sure the tag isn't empty.
Chris@0:                 $string = $phpcsFile->findNext(T_DOC_COMMENT_STRING, $tag, $commentEnd);
Chris@0:                 if ($string === false || $tokens[$string]['line'] !== $tokens[$tag]['line']) {
Chris@0:                     $error = 'Content missing for @see tag in member variable comment';
Chris@0:                     $phpcsFile->addError($error, $tag, 'EmptySees');
Chris@0:                 }
Chris@0:             }//end if
Chris@0:         }//end foreach
Chris@0: 
Chris@0:         // The @var tag is the only one we require.
Chris@0:         if ($foundVar === null) {
Chris@0:             $error = 'Missing @var tag in member variable comment';
Chris@0:             $phpcsFile->addError($error, $commentEnd, 'MissingVar');
Chris@0:             return;
Chris@0:         }
Chris@0: 
Chris@0:         $firstTag = $tokens[$commentStart]['comment_tags'][0];
Chris@0:         if ($foundVar !== null && $tokens[$firstTag]['content'] !== '@var') {
Chris@0:             $error = 'The @var tag must be the first tag in a member variable comment';
Chris@0:             $phpcsFile->addError($error, $foundVar, 'VarOrder');
Chris@0:         }
Chris@0: 
Chris@0:         // Make sure the tag isn't empty and has the correct padding.
Chris@0:         $string = $phpcsFile->findNext(T_DOC_COMMENT_STRING, $foundVar, $commentEnd);
Chris@0:         if ($string === false || $tokens[$string]['line'] !== $tokens[$foundVar]['line']) {
Chris@0:             $error = 'Content missing for @var tag in member variable comment';
Chris@0:             $phpcsFile->addError($error, $foundVar, 'EmptyVar');
Chris@0:             return;
Chris@0:         }
Chris@0: 
Chris@0:         $varType = $tokens[($foundVar + 2)]['content'];
Chris@0: 
Chris@0:         // There may be multiple types separated by pipes.
Chris@0:         $suggestedTypes = array();
Chris@0:         foreach (explode('|', $varType) as $type) {
Chris@17:             $suggestedTypes[] = FunctionCommentSniff::suggestType($type);
Chris@0:         }
Chris@0: 
Chris@0:         $suggestedType = implode('|', $suggestedTypes);
Chris@0: 
Chris@0:         // Detect and auto-fix the common mistake that the variable name is
Chris@0:         // appended to the type declaration.
Chris@0:         $matches = array();
Chris@0:         if (preg_match('/^([^\s]+)(\s+\$.+)$/', $varType, $matches) === 1) {
Chris@0:             $error = 'Do not append variable name "%s" to the type declaration in a member variable comment';
Chris@0:             $data  = array(
Chris@0:                       trim($matches[2]),
Chris@0:                      );
Chris@0:             $fix   = $phpcsFile->addFixableError($error, ($foundVar + 2), 'InlineVariableName', $data);
Chris@0:             if ($fix === true) {
Chris@0:                 $phpcsFile->fixer->replaceToken(($foundVar + 2), $matches[1]);
Chris@0:             }
Chris@0:         } else if ($varType !== $suggestedType) {
Chris@0:             $error = 'Expected "%s" but found "%s" for @var tag in member variable comment';
Chris@0:             $data  = array(
Chris@0:                       $suggestedType,
Chris@0:                       $varType,
Chris@0:                      );
Chris@0:             $fix   = $phpcsFile->addFixableError($error, ($foundVar + 2), 'IncorrectVarType', $data);
Chris@0:             if ($fix === true) {
Chris@0:                 $phpcsFile->fixer->replaceToken(($foundVar + 2), $suggestedType);
Chris@0:             }
Chris@0:         }//end if
Chris@0: 
Chris@0:     }//end processMemberVar()
Chris@0: 
Chris@0: 
Chris@0:     /**
Chris@0:      * Called to process a normal variable.
Chris@0:      *
Chris@0:      * Not required for this sniff.
Chris@0:      *
Chris@17:      * @param \PHP_CodeSniffer\Files\File $phpcsFile The PHP_CodeSniffer file where this token was found.
Chris@17:      * @param int                         $stackPtr  The position where the double quoted
Chris@17:      *                                               string was found.
Chris@0:      *
Chris@0:      * @return void
Chris@0:      */
Chris@17:     protected function processVariable(File $phpcsFile, $stackPtr)
Chris@0:     {
Chris@0: 
Chris@0:     }//end processVariable()
Chris@0: 
Chris@0: 
Chris@0:     /**
Chris@0:      * Called to process variables found in double quoted strings.
Chris@0:      *
Chris@0:      * Not required for this sniff.
Chris@0:      *
Chris@17:      * @param \PHP_CodeSniffer\Files\File $phpcsFile The PHP_CodeSniffer file where this token was found.
Chris@17:      * @param int                         $stackPtr  The position where the double quoted
Chris@17:      *                                               string was found.
Chris@0:      *
Chris@0:      * @return void
Chris@0:      */
Chris@17:     protected function processVariableInString(File $phpcsFile, $stackPtr)
Chris@0:     {
Chris@0: 
Chris@0:     }//end processVariableInString()
Chris@0: 
Chris@0: 
Chris@0: }//end class