Skip to content

Commit 3bd8317

Browse files
sverasvera
authored
Merge pull request #55 from magento-commerce/imported-magento-magento-coding-standard-140
[Imported] #58 : Implement sniff for class properties PHPDoc formatting
2 parents 1e3a89f + 83f7609 commit 3bd8317

17 files changed

+307
-34
lines changed

‎Magento2/Helpers/Tokenizer/AbstractTokenizer.php

-4
Original file line numberDiff line numberDiff line change
@@ -11,15 +11,11 @@
1111
abstract class AbstractTokenizer
1212
{
1313
/**
14-
* Current index in string
15-
*
1614
* @var int
1715
*/
1816
protected $_currentIndex;
1917

2018
/**
21-
* String for tokenize
22-
*
2319
* @var string
2420
*/
2521
protected $_string;

‎Magento2/Helpers/Tokenizer/Variable.php

-2
Original file line numberDiff line numberDiff line change
@@ -12,8 +12,6 @@
1212
class Variable extends AbstractTokenizer
1313
{
1414
/**
15-
* Internal counter used to keep track of how deep in array parsing we are
16-
*
1715
* @var int
1816
*/
1917
protected $arrayDepth = 0;

‎Magento2/Sniffs/Classes/DiscouragedDependenciesSniff.php

-6
Original file line numberDiff line numberDiff line change
@@ -32,22 +32,16 @@ class DiscouragedDependenciesSniff implements Sniff
3232
protected $warningCode = 'ConstructorProxyInterceptor';
3333

3434
/**
35-
* Aliases of proxies or plugins from use statements
36-
*
3735
* @var string[]
3836
*/
3937
private $aliases = [];
4038

4139
/**
42-
* The current file - used for clearing USE aliases when file changes
43-
*
4440
* @var null|string
4541
*/
4642
private $currentFile = null;
4743

4844
/**
49-
* Terms to search for in variables and namespaces
50-
*
5145
* @var string[]
5246
*/
5347
public $incorrectClassNames = ['proxy','interceptor'];

‎Magento2/Sniffs/Commenting/ClassPropertyPHPDocFormattingSniff.php

+158
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,158 @@
1+
<?php
2+
namespace Magento2\Sniffs\Commenting;
3+
4+
use PHP_CodeSniffer\Files\File;
5+
use PHP_CodeSniffer\Sniffs\AbstractVariableSniff;
6+
use PHP_CodeSniffer\Util\Tokens;
7+
use Magento2\Helpers\Commenting\PHPDocFormattingValidator;
8+
9+
/**
10+
* Class ClassPropertyPHPDocFormattingSniff
11+
*/
12+
class ClassPropertyPHPDocFormattingSniff extends AbstractVariableSniff
13+
{
14+
15+
/**
16+
* @var array
17+
*/
18+
private $ignoreTokens = [
19+
T_PUBLIC,
20+
T_PRIVATE,
21+
T_PROTECTED,
22+
T_VAR,
23+
T_STATIC,
24+
T_WHITESPACE,
25+
];
26+
27+
/**
28+
* @var PHPDocFormattingValidator
29+
*/
30+
private $PHPDocFormattingValidator;
31+
32+
/**
33+
* Constructs an ClassPropertyPHPDocFormattingSniff.
34+
*/
35+
public function __construct()
36+
{
37+
$scopes = Tokens::$ooScopeTokens;
38+
$this->PHPDocFormattingValidator = new PHPDocFormattingValidator();
39+
$listen = [
40+
T_VARIABLE,
41+
T_DOUBLE_QUOTED_STRING,
42+
T_HEREDOC,
43+
];
44+
45+
parent::__construct($scopes, $listen, true);
46+
}
47+
48+
/**
49+
* @inheritDoc
50+
*/
51+
public function processMemberVar(File $phpcsFile, $stackPtr)
52+
{
53+
$tokens = $phpcsFile->getTokens();
54+
55+
$commentEnd = $phpcsFile->findPrevious($this->ignoreTokens, ($stackPtr - 1), null, true);
56+
if ($commentEnd === false
57+
|| ($tokens[$commentEnd]['code'] !== T_DOC_COMMENT_CLOSE_TAG
58+
&& $tokens[$commentEnd]['code'] !== T_COMMENT)
59+
) {
60+
$phpcsFile->addWarning('Missing PHP DocBlock for class property.', $stackPtr, 'Missing');
61+
return;
62+
}
63+
$commentStart = $tokens[$commentEnd]['comment_opener'];
64+
$foundVar = null;
65+
foreach ($tokens[$commentStart]['comment_tags'] as $tag) {
66+
if ($tokens[$tag]['content'] === '@var') {
67+
if ($foundVar !== null) {
68+
$error = 'Only one @var tag is allowed for class property declaration.';
69+
$phpcsFile->addWarning($error, $tag, 'DuplicateVar');
70+
} else {
71+
$foundVar = $tag;
72+
}
73+
}
74+
}
75+
76+
if ($foundVar === null) {
77+
$error = 'Class properties must have type declaration using @var tag.';
78+
$phpcsFile->addWarning($error, $stackPtr, 'MissingVar');
79+
return;
80+
}
81+
82+
$string = $phpcsFile->findNext(T_DOC_COMMENT_STRING, $foundVar, $commentEnd);
83+
if ($string === false || $tokens[$string]['line'] !== $tokens[$foundVar]['line']) {
84+
$error = 'Content missing for @var tag in class property declaration.';
85+
$phpcsFile->addWarning($error, $foundVar, 'EmptyVar');
86+
return;
87+
}
88+
89+
// Check if class has already have meaningful description after @var tag
90+
$isShortDescriptionAfterVar = $phpcsFile->findNext(
91+
T_DOC_COMMENT_STRING,
92+
$foundVar + 4,
93+
$commentEnd,
94+
false,
95+
null,
96+
false
97+
);
98+
if ($this->PHPDocFormattingValidator->providesMeaning(
99+
$isShortDescriptionAfterVar,
100+
$commentStart,
101+
$tokens
102+
) !== true) {
103+
preg_match(
104+
'`^((?:\|?(?:array\([^\)]*\)|[\\\\\[\]]+))*)( .*)?`i',
105+
$tokens[($foundVar + 2)]['content'],
106+
$varParts
107+
);
108+
if ($varParts[1]) {
109+
return;
110+
}
111+
$error = 'Short description duplicates class property name.';
112+
$phpcsFile->addWarning($error, $isShortDescriptionAfterVar, 'AlreadyHaveMeaningFulNameVar');
113+
return;
114+
}
115+
// Check if class has already have meaningful description before @var tag
116+
$isShortDescriptionPreviousVar = $phpcsFile->findPrevious(
117+
T_DOC_COMMENT_STRING,
118+
$foundVar,
119+
$commentStart,
120+
false,
121+
null,
122+
false
123+
);
124+
if ($this->PHPDocFormattingValidator->providesMeaning(
125+
$isShortDescriptionPreviousVar,
126+
$commentStart,
127+
$tokens
128+
) !== true) {
129+
preg_match(
130+
'`^((?:\|?(?:array\([^\)]*\)|[\\\\\[\]]+))*)( .*)?`i',
131+
$tokens[($foundVar + 2)]['content'],
132+
$varParts
133+
);
134+
if ($varParts[1]) {
135+
return;
136+
}
137+
$error = 'Short description duplicates class property name.';
138+
$phpcsFile->addWarning($error, $isShortDescriptionPreviousVar, 'AlreadyHaveMeaningFulNameVar');
139+
return;
140+
}
141+
}
142+
143+
/**
144+
* @inheritDoc
145+
* phpcs:disable Magento2.CodeAnalysis.EmptyBlock
146+
*/
147+
protected function processVariable(File $phpcsFile, $stackPtr)
148+
{
149+
}
150+
151+
/**
152+
* @inheritDoc
153+
* phpcs:disable Magento2.CodeAnalysis.EmptyBlock
154+
*/
155+
protected function processVariableInString(File $phpcsFile, $stackPtr)
156+
{
157+
}
158+
}

‎Magento2/Sniffs/Exceptions/DirectThrowSniff.php

+1
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,7 @@ class DirectThrowSniff implements Sniff
1616
/**
1717
* String representation of warning.
1818
* phpcs:disable Generic.Files.LineLength.TooLong
19+
* @var string
1920
*/
2021
protected $warningMessage = 'Direct throw of generic Exception is discouraged. Use context specific instead.';
2122
//phpcs:enable

‎Magento2/Sniffs/Less/AvoidIdSniff.php

-2
Original file line numberDiff line numberDiff line change
@@ -25,8 +25,6 @@ class AvoidIdSniff implements Sniff
2525
public $supportedTokenizers = [TokenizerSymbolsInterface::TOKENIZER_CSS];
2626

2727
/**
28-
* Tokens that can appear in a selector
29-
*
3028
* @var array
3129
*/
3230
private $selectorTokens = [

‎Magento2/Sniffs/Less/IndentationSniff.php

+1-2
Original file line numberDiff line numberDiff line change
@@ -39,8 +39,7 @@ class IndentationSniff implements Sniff
3939
*/
4040
public $maxIndentLevel = 3;
4141

42-
/** Skip codes that can be detected by sniffer incorrectly
43-
*
42+
/**
4443
* @var array
4544
*/
4645
private $styleCodesToSkip = [T_ASPERAND, T_COLON, T_OPEN_PARENTHESIS, T_CLOSE_PARENTHESIS];

‎Magento2/Sniffs/Less/PropertiesSortingSniff.php

-4
Original file line numberDiff line numberDiff line change
@@ -25,15 +25,11 @@ class PropertiesSortingSniff implements Sniff
2525
public $supportedTokenizers = [TokenizerSymbolsInterface::TOKENIZER_CSS];
2626

2727
/**
28-
* List of properties that belong to class
29-
*
3028
* @var array
3129
*/
3230
private $properties = [];
3331

3432
/**
35-
* Skip symbols that can be detected by sniffer incorrectly
36-
*
3733
* @var array
3834
*/
3935
private $styleSymbolsToSkip = [

‎Magento2/Sniffs/Less/SemicolonSpacingSniff.php

+1-4
Original file line numberDiff line numberDiff line change
@@ -25,8 +25,6 @@ class SemicolonSpacingSniff implements Sniff
2525
public $supportedTokenizers = [TokenizerSymbolsInterface::TOKENIZER_CSS];
2626

2727
/**
28-
* Skip symbols that can be detected by sniffer incorrectly
29-
*
3028
* @var array
3129
*/
3230
private $styleSymbolsToSkip = [
@@ -36,8 +34,7 @@ class SemicolonSpacingSniff implements Sniff
3634
TokenizerSymbolsInterface::CLOSE_PARENTHESIS,
3735
];
3836

39-
/** Skip codes that can be detected by sniffer incorrectly
40-
*
37+
/**
4138
* @var array
4239
*/
4340
private $styleCodesToSkip = [T_ASPERAND, T_COLON, T_OPEN_PARENTHESIS, T_CLOSE_PARENTHESIS];

‎Magento2/Sniffs/Less/TypeSelectorsSniff.php

-2
Original file line numberDiff line numberDiff line change
@@ -23,8 +23,6 @@
2323
class TypeSelectorsSniff implements Sniff
2424
{
2525
/**
26-
* Tags that are not allowed as type selector
27-
*
2826
* @var array
2927
*/
3028
private $tags = [

‎Magento2/Sniffs/Less/ZeroUnitsSniff.php

-2
Original file line numberDiff line numberDiff line change
@@ -24,8 +24,6 @@ class ZeroUnitsSniff implements Sniff
2424
const CSS_PROPERTY_UNIT_REM = 'rem';
2525

2626
/**
27-
* List of available CSS Property units
28-
*
2927
* @var array
3028
*/
3129
private $units = [

‎Magento2/Sniffs/Methods/DeprecatedModelMethodSniff.php

-2
Original file line numberDiff line numberDiff line change
@@ -40,8 +40,6 @@ class DeprecatedModelMethodSniff implements Sniff
4040
'delete'
4141
];
4242

43-
protected $severity = 0;
44-
4543
/**
4644
* @inheritdoc
4745
*/

‎Magento2/Sniffs/Security/SuperglobalSniff.php

+2-2
Original file line numberDiff line numberDiff line change
@@ -42,7 +42,7 @@ class SuperglobalSniff implements Sniff
4242
protected $errorCode = 'SuperglobalUsageError';
4343

4444
/**
45-
* @inheritdoc
45+
* @var array
4646
*/
4747
protected $superGlobalErrors = [
4848
'$GLOBALS',
@@ -55,7 +55,7 @@ class SuperglobalSniff implements Sniff
5555
];
5656

5757
/**
58-
* @inheritdoc
58+
* @var array
5959
*/
6060
protected $superGlobalWarning = [
6161
'$_COOKIE', //sometimes need to get list of all cookies array and there are no methods to do that in M2

‎Magento2/Sniffs/Security/XssTemplateSniff.php

-2
Original file line numberDiff line numberDiff line change
@@ -50,8 +50,6 @@ class XssTemplateSniff implements Sniff
5050
];
5151

5252
/**
53-
* Allowed method name - {suffix}Html{postfix}()
54-
*
5553
* @var string
5654
*/
5755
protected $methodNameContains = 'html';

0 commit comments

Comments
 (0)