Page Menu
Home
WickedGov Phorge
Search
Configure Global Search
Log In
Files
F7396748
FunctionCommentSniff.php
No One
Temporary
Actions
Download File
Edit File
Delete File
View Transforms
Subscribe
Flag For Later
Award Token
Size
20 KB
Referenced Files
None
Subscribers
None
FunctionCommentSniff.php
View Options
<?php
/**
* Parses and verifies the doc comments for functions.
*
* @author Greg Sherwood <gsherwood@squiz.net>
* @copyright 2006-2015 Squiz Pty Ltd (ABN 77 084 670 600)
* @license https://github.com/PHPCSStandards/PHP_CodeSniffer/blob/master/licence.txt BSD Licence
*/
namespace
PHP_CodeSniffer\Standards\PEAR\Sniffs\Commenting
;
use
PHP_CodeSniffer\Files\File
;
use
PHP_CodeSniffer\Sniffs\Sniff
;
use
PHP_CodeSniffer\Util\Tokens
;
class
FunctionCommentSniff
implements
Sniff
{
/**
* Disable the check for functions with a lower visibility than the value given.
*
* Allowed values are public, protected, and private.
*
* @var string
*/
public
$minimumVisibility
=
'private'
;
/**
* Array of methods which do not require a return type.
*
* @var array
*/
public
$specialMethods
=
[
'__construct'
,
'__destruct'
,
];
/**
* Returns an array of tokens this test wants to listen for.
*
* @return array<int|string>
*/
public
function
register
()
{
return
[
T_FUNCTION
];
}
//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
)
{
$scopeModifier
=
$phpcsFile
->
getMethodProperties
(
$stackPtr
)[
'scope'
];
if
((
$scopeModifier
===
'protected'
&&
$this
->
minimumVisibility
===
'public'
)
||
(
$scopeModifier
===
'private'
&&
(
$this
->
minimumVisibility
===
'public'
||
$this
->
minimumVisibility
===
'protected'
))
)
{
return
;
}
$tokens
=
$phpcsFile
->
getTokens
();
$ignore
=
Tokens
::
$methodPrefixes
;
$ignore
[
T_WHITESPACE
]
=
T_WHITESPACE
;
for
(
$commentEnd
=
(
$stackPtr
-
1
);
$commentEnd
>=
0
;
$commentEnd
--)
{
if
(
isset
(
$ignore
[
$tokens
[
$commentEnd
][
'code'
]])
===
true
)
{
continue
;
}
if
(
$tokens
[
$commentEnd
][
'code'
]
===
T_ATTRIBUTE_END
&&
isset
(
$tokens
[
$commentEnd
][
'attribute_opener'
])
===
true
)
{
$commentEnd
=
$tokens
[
$commentEnd
][
'attribute_opener'
];
continue
;
}
break
;
}
if
(
$tokens
[
$commentEnd
][
'code'
]
===
T_COMMENT
)
{
// Inline comments might just be closing comments for
// control structures or functions instead of function comments
// using the wrong comment type. If there is other code on the line,
// assume they relate to that code.
$prev
=
$phpcsFile
->
findPrevious
(
$ignore
,
(
$commentEnd
-
1
),
null
,
true
);
if
(
$prev
!==
false
&&
$tokens
[
$prev
][
'line'
]
===
$tokens
[
$commentEnd
][
'line'
])
{
$commentEnd
=
$prev
;
}
}
if
(
$tokens
[
$commentEnd
][
'code'
]
!==
T_DOC_COMMENT_CLOSE_TAG
&&
$tokens
[
$commentEnd
][
'code'
]
!==
T_COMMENT
)
{
$function
=
$phpcsFile
->
getDeclarationName
(
$stackPtr
);
$phpcsFile
->
addError
(
'Missing doc comment for function %s()'
,
$stackPtr
,
'Missing'
,
[
$function
]
);
$phpcsFile
->
recordMetric
(
$stackPtr
,
'Function has doc comment'
,
'no'
);
return
;
}
else
{
$phpcsFile
->
recordMetric
(
$stackPtr
,
'Function has doc comment'
,
'yes'
);
}
if
(
$tokens
[
$commentEnd
][
'code'
]
===
T_COMMENT
)
{
$phpcsFile
->
addError
(
'You must use "/**" style comments for a function comment'
,
$stackPtr
,
'WrongStyle'
);
return
;
}
if
(
$tokens
[
$commentEnd
][
'line'
]
!==
(
$tokens
[
$stackPtr
][
'line'
]
-
1
))
{
for
(
$i
=
(
$commentEnd
+
1
);
$i
<
$stackPtr
;
$i
++)
{
if
(
$tokens
[
$i
][
'column'
]
!==
1
)
{
continue
;
}
if
(
$tokens
[
$i
][
'code'
]
===
T_WHITESPACE
&&
$tokens
[
$i
][
'line'
]
!==
$tokens
[(
$i
+
1
)][
'line'
]
)
{
$error
=
'There must be no blank lines after the function comment'
;
$fix
=
$phpcsFile
->
addFixableError
(
$error
,
$commentEnd
,
'SpacingAfter'
);
if
(
$fix
===
true
)
{
$phpcsFile
->
fixer
->
beginChangeset
();
while
(
$i
<
$stackPtr
&&
$tokens
[
$i
][
'code'
]
===
T_WHITESPACE
&&
$tokens
[
$i
][
'line'
]
!==
$tokens
[(
$i
+
1
)][
'line'
]
)
{
$phpcsFile
->
fixer
->
replaceToken
(
$i
++,
''
);
}
$phpcsFile
->
fixer
->
endChangeset
();
}
break
;
}
}
//end for
}
//end if
$commentStart
=
$tokens
[
$commentEnd
][
'comment_opener'
];
foreach
(
$tokens
[
$commentStart
][
'comment_tags'
]
as
$tag
)
{
if
(
$tokens
[
$tag
][
'content'
]
===
'@see'
)
{
// Make sure the tag isn't empty.
$string
=
$phpcsFile
->
findNext
(
T_DOC_COMMENT_STRING
,
$tag
,
$commentEnd
);
if
(
$string
===
false
||
$tokens
[
$string
][
'line'
]
!==
$tokens
[
$tag
][
'line'
])
{
$error
=
'Content missing for @see tag in function comment'
;
$phpcsFile
->
addError
(
$error
,
$tag
,
'EmptySees'
);
}
}
}
$this
->
processReturn
(
$phpcsFile
,
$stackPtr
,
$commentStart
);
$this
->
processThrows
(
$phpcsFile
,
$stackPtr
,
$commentStart
);
$this
->
processParams
(
$phpcsFile
,
$stackPtr
,
$commentStart
);
}
//end process()
/**
* Process the return comment of this function comment.
*
* @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.
* @param int $commentStart The position in the stack where the comment started.
*
* @return void
*/
protected
function
processReturn
(
File
$phpcsFile
,
$stackPtr
,
$commentStart
)
{
$tokens
=
$phpcsFile
->
getTokens
();
// Skip constructor and destructor.
$methodName
=
$phpcsFile
->
getDeclarationName
(
$stackPtr
);
$isSpecialMethod
=
in_array
(
$methodName
,
$this
->
specialMethods
,
true
);
$return
=
null
;
foreach
(
$tokens
[
$commentStart
][
'comment_tags'
]
as
$tag
)
{
if
(
$tokens
[
$tag
][
'content'
]
===
'@return'
)
{
if
(
$return
!==
null
)
{
$error
=
'Only 1 @return tag is allowed in a function comment'
;
$phpcsFile
->
addError
(
$error
,
$tag
,
'DuplicateReturn'
);
return
;
}
$return
=
$tag
;
}
}
if
(
$return
!==
null
)
{
$content
=
$tokens
[(
$return
+
2
)][
'content'
];
if
(
empty
(
$content
)
===
true
||
$tokens
[(
$return
+
2
)][
'code'
]
!==
T_DOC_COMMENT_STRING
)
{
$error
=
'Return type missing for @return tag in function comment'
;
$phpcsFile
->
addError
(
$error
,
$return
,
'MissingReturnType'
);
}
}
else
{
if
(
$isSpecialMethod
===
true
)
{
return
;
}
$error
=
'Missing @return tag in function comment'
;
$phpcsFile
->
addError
(
$error
,
$tokens
[
$commentStart
][
'comment_closer'
],
'MissingReturn'
);
}
//end if
}
//end processReturn()
/**
* Process any throw tags that this function comment has.
*
* @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.
* @param int $commentStart The position in the stack where the comment started.
*
* @return void
*/
protected
function
processThrows
(
File
$phpcsFile
,
$stackPtr
,
$commentStart
)
{
$tokens
=
$phpcsFile
->
getTokens
();
foreach
(
$tokens
[
$commentStart
][
'comment_tags'
]
as
$tag
)
{
if
(
$tokens
[
$tag
][
'content'
]
!==
'@throws'
)
{
continue
;
}
$exception
=
null
;
if
(
$tokens
[(
$tag
+
2
)][
'code'
]
===
T_DOC_COMMENT_STRING
)
{
$matches
=
[];
preg_match
(
'/([^
\s
]+)(?:
\s
+(.*))?/'
,
$tokens
[(
$tag
+
2
)][
'content'
],
$matches
);
$exception
=
$matches
[
1
];
}
if
(
$exception
===
null
)
{
$error
=
'Exception type missing for @throws tag in function comment'
;
$phpcsFile
->
addError
(
$error
,
$tag
,
'InvalidThrows'
);
}
}
//end foreach
}
//end processThrows()
/**
* Process the function parameter comments.
*
* @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.
* @param int $commentStart The position in the stack where the comment started.
*
* @return void
*/
protected
function
processParams
(
File
$phpcsFile
,
$stackPtr
,
$commentStart
)
{
$tokens
=
$phpcsFile
->
getTokens
();
$params
=
[];
$maxType
=
0
;
$maxVar
=
0
;
foreach
(
$tokens
[
$commentStart
][
'comment_tags'
]
as
$pos
=>
$tag
)
{
if
(
$tokens
[
$tag
][
'content'
]
!==
'@param'
)
{
continue
;
}
$type
=
''
;
$typeSpace
=
0
;
$var
=
''
;
$varSpace
=
0
;
$comment
=
''
;
$commentEnd
=
0
;
$commentTokens
=
[];
if
(
$tokens
[(
$tag
+
2
)][
'code'
]
===
T_DOC_COMMENT_STRING
)
{
$matches
=
[];
preg_match
(
'/((?:(?![$.]|&(?=
\$
)).)*)(?:((?:
\.\.\.
)?(?:
\$
|&)[^
\s
]+)(?:(
\s
+)(.*))?)?/'
,
$tokens
[(
$tag
+
2
)][
'content'
],
$matches
);
if
(
empty
(
$matches
)
===
false
)
{
$typeLen
=
strlen
(
$matches
[
1
]);
$type
=
trim
(
$matches
[
1
]);
$typeSpace
=
(
$typeLen
-
strlen
(
$type
));
$typeLen
=
strlen
(
$type
);
if
(
$typeLen
>
$maxType
)
{
$maxType
=
$typeLen
;
}
}
if
(
isset
(
$matches
[
2
])
===
true
)
{
$var
=
$matches
[
2
];
$varLen
=
strlen
(
$var
);
if
(
$varLen
>
$maxVar
)
{
$maxVar
=
$varLen
;
}
if
(
isset
(
$matches
[
4
])
===
true
)
{
$varSpace
=
strlen
(
$matches
[
3
]);
$comment
=
$matches
[
4
];
// Any strings until the next tag belong to this comment.
if
(
isset
(
$tokens
[
$commentStart
][
'comment_tags'
][(
$pos
+
1
)])
===
true
)
{
$end
=
$tokens
[
$commentStart
][
'comment_tags'
][(
$pos
+
1
)];
}
else
{
$end
=
$tokens
[
$commentStart
][
'comment_closer'
];
}
for
(
$i
=
(
$tag
+
3
);
$i
<
$end
;
$i
++)
{
if
(
$tokens
[
$i
][
'code'
]
===
T_DOC_COMMENT_STRING
)
{
$comment
.=
' '
.
$tokens
[
$i
][
'content'
];
$commentEnd
=
$i
;
$commentTokens
[]
=
$i
;
}
}
}
else
{
$error
=
'Missing parameter comment'
;
$phpcsFile
->
addError
(
$error
,
$tag
,
'MissingParamComment'
);
}
//end if
}
else
{
$error
=
'Missing parameter name'
;
$phpcsFile
->
addError
(
$error
,
$tag
,
'MissingParamName'
);
}
//end if
}
else
{
$error
=
'Missing parameter type'
;
$phpcsFile
->
addError
(
$error
,
$tag
,
'MissingParamType'
);
}
//end if
$params
[]
=
[
'tag'
=>
$tag
,
'type'
=>
$type
,
'var'
=>
$var
,
'comment'
=>
$comment
,
'comment_end'
=>
$commentEnd
,
'comment_tokens'
=>
$commentTokens
,
'type_space'
=>
$typeSpace
,
'var_space'
=>
$varSpace
,
];
}
//end foreach
$realParams
=
$phpcsFile
->
getMethodParameters
(
$stackPtr
);
$foundParams
=
[];
// We want to use ... for all variable length arguments, so add
// this prefix to the variable name so comparisons are easier.
foreach
(
$realParams
as
$pos
=>
$param
)
{
if
(
$param
[
'variable_length'
]
===
true
)
{
$realParams
[
$pos
][
'name'
]
=
'...'
.
$realParams
[
$pos
][
'name'
];
}
}
foreach
(
$params
as
$pos
=>
$param
)
{
if
(
$param
[
'var'
]
===
''
)
{
continue
;
}
$foundParams
[]
=
$param
[
'var'
];
if
(
trim
(
$param
[
'type'
])
!==
''
)
{
// Check number of spaces after the type.
$spaces
=
(
$maxType
-
strlen
(
$param
[
'type'
])
+
1
);
if
(
$param
[
'type_space'
]
!==
$spaces
)
{
$error
=
'Expected %s spaces after parameter type; %s found'
;
$data
=
[
$spaces
,
$param
[
'type_space'
],
];
$fix
=
$phpcsFile
->
addFixableError
(
$error
,
$param
[
'tag'
],
'SpacingAfterParamType'
,
$data
);
if
(
$fix
===
true
)
{
$commentToken
=
(
$param
[
'tag'
]
+
2
);
$content
=
$param
[
'type'
];
$content
.=
str_repeat
(
' '
,
$spaces
);
$content
.=
$param
[
'var'
];
$content
.=
str_repeat
(
' '
,
$param
[
'var_space'
]);
$wrapLength
=
(
$tokens
[
$commentToken
][
'length'
]
-
$param
[
'type_space'
]
-
$param
[
'var_space'
]
-
strlen
(
$param
[
'type'
])
-
strlen
(
$param
[
'var'
]));
$star
=
$phpcsFile
->
findPrevious
(
T_DOC_COMMENT_STAR
,
$param
[
'tag'
]);
$spaceLength
=
(
strlen
(
$content
)
+
$tokens
[(
$commentToken
-
1
)][
'length'
]
+
$tokens
[(
$commentToken
-
2
)][
'length'
]);
$padding
=
str_repeat
(
' '
,
(
$tokens
[
$star
][
'column'
]
-
1
));
$padding
.=
'* '
;
$padding
.=
str_repeat
(
' '
,
$spaceLength
);
$content
.=
wordwrap
(
$param
[
'comment'
],
$wrapLength
,
$phpcsFile
->
eolChar
.
$padding
);
$phpcsFile
->
fixer
->
replaceToken
(
$commentToken
,
$content
);
for
(
$i
=
(
$commentToken
+
1
);
$i
<=
$param
[
'comment_end'
];
$i
++)
{
$phpcsFile
->
fixer
->
replaceToken
(
$i
,
''
);
}
}
//end if
}
//end if
}
//end if
// Make sure the param name is correct.
if
(
isset
(
$realParams
[
$pos
])
===
true
)
{
$realName
=
$realParams
[
$pos
][
'name'
];
if
(
$realName
!==
$param
[
'var'
])
{
$code
=
'ParamNameNoMatch'
;
$data
=
[
$param
[
'var'
],
$realName
,
];
$error
=
'Doc comment for parameter %s does not match '
;
if
(
strtolower
(
$param
[
'var'
])
===
strtolower
(
$realName
))
{
$error
.=
'case of '
;
$code
=
'ParamNameNoCaseMatch'
;
}
$error
.=
'actual variable name %s'
;
$phpcsFile
->
addError
(
$error
,
$param
[
'tag'
],
$code
,
$data
);
}
}
else
if
(
substr
(
$param
[
'var'
],
-
4
)
!==
',...'
)
{
// We must have an extra parameter comment.
$error
=
'Superfluous parameter comment'
;
$phpcsFile
->
addError
(
$error
,
$param
[
'tag'
],
'ExtraParamComment'
);
}
//end if
if
(
$param
[
'comment'
]
===
''
)
{
continue
;
}
// Check number of spaces after the param name.
$spaces
=
(
$maxVar
-
strlen
(
$param
[
'var'
])
+
1
);
if
(
$param
[
'var_space'
]
!==
$spaces
)
{
$error
=
'Expected %s spaces after parameter name; %s found'
;
$data
=
[
$spaces
,
$param
[
'var_space'
],
];
$fix
=
$phpcsFile
->
addFixableError
(
$error
,
$param
[
'tag'
],
'SpacingAfterParamName'
,
$data
);
if
(
$fix
===
true
)
{
$commentToken
=
(
$param
[
'tag'
]
+
2
);
$content
=
$param
[
'type'
];
$content
.=
str_repeat
(
' '
,
$param
[
'type_space'
]);
$content
.=
$param
[
'var'
];
$content
.=
str_repeat
(
' '
,
$spaces
);
$wrapLength
=
(
$tokens
[
$commentToken
][
'length'
]
-
$param
[
'type_space'
]
-
$param
[
'var_space'
]
-
strlen
(
$param
[
'type'
])
-
strlen
(
$param
[
'var'
]));
$star
=
$phpcsFile
->
findPrevious
(
T_DOC_COMMENT_STAR
,
$param
[
'tag'
]);
$spaceLength
=
(
strlen
(
$content
)
+
$tokens
[(
$commentToken
-
1
)][
'length'
]
+
$tokens
[(
$commentToken
-
2
)][
'length'
]);
$padding
=
str_repeat
(
' '
,
(
$tokens
[
$star
][
'column'
]
-
1
));
$padding
.=
'* '
;
$padding
.=
str_repeat
(
' '
,
$spaceLength
);
$content
.=
wordwrap
(
$param
[
'comment'
],
$wrapLength
,
$phpcsFile
->
eolChar
.
$padding
);
$phpcsFile
->
fixer
->
replaceToken
(
$commentToken
,
$content
);
for
(
$i
=
(
$commentToken
+
1
);
$i
<=
$param
[
'comment_end'
];
$i
++)
{
$phpcsFile
->
fixer
->
replaceToken
(
$i
,
''
);
}
}
//end if
}
//end if
// Check the alignment of multi-line param comments.
if
(
$param
[
'tag'
]
!==
$param
[
'comment_end'
])
{
$wrapLength
=
(
$tokens
[(
$param
[
'tag'
]
+
2
)][
'length'
]
-
$param
[
'type_space'
]
-
$param
[
'var_space'
]
-
strlen
(
$param
[
'type'
])
-
strlen
(
$param
[
'var'
]));
$startColumn
=
(
$tokens
[(
$param
[
'tag'
]
+
2
)][
'column'
]
+
$tokens
[(
$param
[
'tag'
]
+
2
)][
'length'
]
-
$wrapLength
);
$star
=
$phpcsFile
->
findPrevious
(
T_DOC_COMMENT_STAR
,
$param
[
'tag'
]);
$expected
=
(
$startColumn
-
$tokens
[
$star
][
'column'
]
-
1
);
foreach
(
$param
[
'comment_tokens'
]
as
$commentToken
)
{
if
(
$tokens
[
$commentToken
][
'column'
]
===
$startColumn
)
{
continue
;
}
$found
=
0
;
if
(
$tokens
[(
$commentToken
-
1
)][
'code'
]
===
T_DOC_COMMENT_WHITESPACE
)
{
$found
=
$tokens
[(
$commentToken
-
1
)][
'length'
];
}
$error
=
'Parameter comment not aligned correctly; expected %s spaces but found %s'
;
$data
=
[
$expected
,
$found
,
];
if
(
$found
<
$expected
)
{
$code
=
'ParamCommentAlignment'
;
}
else
{
$code
=
'ParamCommentAlignmentExceeded'
;
}
$fix
=
$phpcsFile
->
addFixableError
(
$error
,
$commentToken
,
$code
,
$data
);
if
(
$fix
===
true
)
{
$padding
=
str_repeat
(
' '
,
$expected
);
if
(
$tokens
[(
$commentToken
-
1
)][
'code'
]
===
T_DOC_COMMENT_WHITESPACE
)
{
$phpcsFile
->
fixer
->
replaceToken
((
$commentToken
-
1
),
$padding
);
}
else
{
$phpcsFile
->
fixer
->
addContentBefore
(
$commentToken
,
$padding
);
}
}
}
//end foreach
}
//end if
}
//end foreach
$realNames
=
[];
foreach
(
$realParams
as
$realParam
)
{
$realNames
[]
=
$realParam
[
'name'
];
}
// Report missing comments.
$diff
=
array_diff
(
$realNames
,
$foundParams
);
foreach
(
$diff
as
$neededParam
)
{
$error
=
'Doc comment for parameter "%s" missing'
;
$data
=
[
$neededParam
];
$phpcsFile
->
addError
(
$error
,
$commentStart
,
'MissingParamTag'
,
$data
);
}
}
//end processParams()
}
//end class
File Metadata
Details
Attached
Mime Type
text/x-php
Expires
Sat, Nov 21, 14:20 (5 h, 42 m ago)
Storage Engine
local-disk
Storage Format
Raw Data
Storage Handle
8a/2d/d02c5b38ffa70b6783c8ee29b5cd
Default Alt Text
FunctionCommentSniff.php (20 KB)
Attached To
Mode
rMWPROD MediaWiki Production
Attached
Detach File
Event Timeline
Log In to Comment