Skip to content

Commit d3cacbe

Browse files
lenaorobeilenaorobei
committed
Merge branch 'develop' of github.com:magento/magento-coding-standard into 21-system-resources
2 parents 859e563 + 925b97b commit d3cacbe

File tree

49 files changed

+747
-315
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

49 files changed

+747
-315
lines changed

‎.travis.yml

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,7 @@ php:
44
- 7.0
55
- 7.1
66
- 7.2
7+
- 7.3
78
install: composer install --no-interaction --prefer-source
89
script:
910
- vendor/bin/phpunit

‎Magento2/Sniffs/CodeAnalysis/EmptyBlockSniff.php

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,7 @@
55
*/
66
namespace Magento2\Sniffs\CodeAnalysis;
77

8+
use PHP_CodeSniffer\Files\File;
89
use PHP_CodeSniffer\Standards\Generic\Sniffs\CodeAnalysis\EmptyStatementSniff;
910

1011
/**
@@ -25,4 +26,17 @@ public function register()
2526
]
2627
);
2728
}
29+
/**
30+
* @inheritDoc
31+
*/
32+
public function process(File $phpcsFile, $stackPtr)
33+
{
34+
$tokens = $phpcsFile->getTokens();
35+
if ($tokens[$stackPtr]['code'] === T_FUNCTION &&
36+
strpos($phpcsFile->getDeclarationName($stackPtr), 'around') === 0) {
37+
return;
38+
}
39+
40+
parent::process($phpcsFile, $stackPtr);
41+
}//end process()
2842
}

‎Magento2/Sniffs/Commenting/ClassAndInterfacePHPDocFormattingSniff.php

Lines changed: 121 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,121 @@
1+
<?php
2+
3+
/**
4+
* Copyright © Magento. All rights reserved.
5+
* See COPYING.txt for license details.
6+
*/
7+
namespace Magento2\Sniffs\Commenting;
8+
9+
use PHP_CodeSniffer\Sniffs\Sniff;
10+
use PHP_CodeSniffer\Files\File;
11+
12+
/**
13+
* Detects PHPDoc formatting for classes and interfaces.
14+
*/
15+
class ClassAndInterfacePHPDocFormattingSniff implements Sniff
16+
{
17+
/**
18+
* @var PHPDocFormattingValidator
19+
*/
20+
private $PHPDocFormattingValidator;
21+
22+
/**
23+
* @var string[] List of tags that can not be used in comments
24+
*/
25+
public $forbiddenTags = [
26+
'@category',
27+
'@package',
28+
'@subpackage'
29+
];
30+
31+
/**
32+
* Helper initialisation
33+
*/
34+
public function __construct()
35+
{
36+
$this->PHPDocFormattingValidator = new PHPDocFormattingValidator();
37+
}
38+
39+
/**
40+
* @inheritDoc
41+
*/
42+
public function register()
43+
{
44+
return [
45+
T_CLASS,
46+
T_INTERFACE
47+
];
48+
}
49+
50+
/**
51+
* @inheritDoc
52+
*/
53+
public function process(File $phpcsFile, $stackPtr)
54+
{
55+
$tokens = $phpcsFile->getTokens();
56+
57+
$namePtr = $phpcsFile->findNext(T_STRING, $stackPtr + 1, null, false, null, true);
58+
59+
$commentStartPtr = $phpcsFile->findPrevious(
60+
[
61+
T_WHITESPACE,
62+
T_DOC_COMMENT_STAR,
63+
T_DOC_COMMENT_WHITESPACE,
64+
T_DOC_COMMENT_TAG,
65+
T_DOC_COMMENT_STRING,
66+
T_DOC_COMMENT_CLOSE_TAG
67+
],
68+
$stackPtr - 1,
69+
null,
70+
true,
71+
null,
72+
true
73+
);
74+
75+
if ($tokens[$commentStartPtr]['code'] !== T_DOC_COMMENT_OPEN_TAG) {
76+
return;
77+
}
78+
79+
if ($this->PHPDocFormattingValidator->providesMeaning($namePtr, $commentStartPtr, $tokens) !== true) {
80+
$phpcsFile->addWarning(
81+
sprintf(
82+
'%s description should contain additional information beyond the name already supplies.',
83+
ucfirst($tokens[$stackPtr]['content'])
84+
),
85+
$stackPtr,
86+
'InvalidDescription'
87+
);
88+
}
89+
90+
$this->validateTags($phpcsFile, $commentStartPtr, $tokens);
91+
}
92+
93+
/**
94+
* Validates that forbidden tags are not used in comment
95+
*
96+
* @param File $phpcsFile
97+
* @param int $commentStartPtr
98+
* @param array $tokens
99+
* @return bool
100+
*/
101+
private function validateTags(File $phpcsFile, $commentStartPtr, $tokens)
102+
{
103+
$commentCloserPtr = $tokens[$commentStartPtr]['comment_closer'];
104+
105+
for ($i = $commentStartPtr; $i <= $commentCloserPtr; $i++) {
106+
if ($tokens[$i]['code'] !== T_DOC_COMMENT_TAG) {
107+
continue;
108+
}
109+
110+
if (in_array($tokens[$i]['content'], $this->forbiddenTags) === true) {
111+
$phpcsFile->addWarning(
112+
sprintf('Tag %s MUST NOT be used.', $tokens[$i]['content']),
113+
$i,
114+
'ForbiddenTags'
115+
);
116+
}
117+
}
118+
119+
return false;
120+
}
121+
}

‎Magento2/Sniffs/Commenting/ConstantsPHPDocFormattingSniff.php

Lines changed: 75 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,75 @@
1+
<?php
2+
/**
3+
* Copyright © Magento. All rights reserved.
4+
* See COPYING.txt for license details.
5+
*/
6+
namespace Magento2\Sniffs\Commenting;
7+
8+
use PHP_CodeSniffer\Sniffs\Sniff;
9+
use PHP_CodeSniffer\Files\File;
10+
11+
/**
12+
* Detects PHPDoc formatting for constants.
13+
*/
14+
class ConstantsPHPDocFormattingSniff implements Sniff
15+
{
16+
/**
17+
* @var PHPDocFormattingValidator
18+
*/
19+
private $PHPDocFormattingValidator;
20+
21+
/**
22+
* Helper initialisation
23+
*/
24+
public function __construct()
25+
{
26+
$this->PHPDocFormattingValidator = new PHPDocFormattingValidator();
27+
}
28+
29+
/**
30+
* @inheritDoc
31+
*/
32+
public function register()
33+
{
34+
return [
35+
T_CONST,
36+
T_STRING
37+
];
38+
}
39+
40+
/**
41+
* @inheritDoc
42+
*/
43+
public function process(File $phpcsFile, $stackPtr)
44+
{
45+
$tokens = $phpcsFile->getTokens();
46+
47+
if ($tokens[$stackPtr]['code'] !== T_CONST
48+
&& !($tokens[$stackPtr]['content'] === 'define' && $tokens[$stackPtr + 1]['code'] === T_OPEN_PARENTHESIS)
49+
) {
50+
return;
51+
}
52+
53+
$constNamePtr = $phpcsFile->findNext(
54+
($tokens[$stackPtr]['code'] === T_CONST) ? T_STRING : T_CONSTANT_ENCAPSED_STRING,
55+
$stackPtr + 1,
56+
null,
57+
false,
58+
null,
59+
true
60+
);
61+
62+
$commentStartPtr = $phpcsFile->findPrevious(T_DOC_COMMENT_OPEN_TAG, $stackPtr - 1, null, false, null, true);
63+
if ($commentStartPtr === false) {
64+
return;
65+
}
66+
67+
if ($this->PHPDocFormattingValidator->providesMeaning($constNamePtr, $commentStartPtr, $tokens) !== true) {
68+
$phpcsFile->addWarning(
69+
'Constants must have short description if they add information beyond what the constant name supplies.',
70+
$stackPtr,
71+
'MissingConstantPHPDoc'
72+
);
73+
}
74+
}
75+
}

‎Magento2/Sniffs/Commenting/PHPDocFormattingValidator.php

Lines changed: 74 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,74 @@
1+
<?php
2+
3+
/**
4+
* Copyright © Magento. All rights reserved.
5+
* See COPYING.txt for license details.
6+
*/
7+
namespace Magento2\Sniffs\Commenting;
8+
9+
/**
10+
* Helper class for common DocBlock validations
11+
*/
12+
class PHPDocFormattingValidator
13+
{
14+
/**
15+
* Determines if the comment identified by $commentStartPtr provides additional meaning to origin at $namePtr
16+
*
17+
* @param int $namePtr
18+
* @param int $commentStartPtr
19+
* @param array $tokens
20+
* @return bool
21+
*/
22+
public function providesMeaning($namePtr, $commentStartPtr, $tokens)
23+
{
24+
$commentCloserPtr = $tokens[$commentStartPtr]['comment_closer'];
25+
$name = strtolower(str_replace([' ', '"', '_'], '', $tokens[$namePtr]['content']));
26+
27+
$hasTags = false;
28+
$hasDescription = false;
29+
30+
for ($i = $commentStartPtr; $i <= $commentCloserPtr; $i++) {
31+
$token = $tokens[$i];
32+
33+
// Important, but not the string we are looking for
34+
if ($token['code'] === T_DOC_COMMENT_TAG) {
35+
$hasTags = true;
36+
continue;
37+
}
38+
39+
// Not an interesting string
40+
if ($token['code'] !== T_DOC_COMMENT_STRING) {
41+
continue;
42+
}
43+
44+
// Wrong kind of string
45+
if ($tokens[$i - 2]['code'] === T_DOC_COMMENT_TAG) {
46+
continue;
47+
}
48+
49+
$hasDescription = true;
50+
51+
// Comment is the same as the origin name
52+
$docComment = str_replace(['_', ' ', '.', ','], '', strtolower($token['content']));
53+
if ($docComment === $name) {
54+
continue;
55+
}
56+
57+
// Only difference is word Class or Interface
58+
$docComment = str_replace(['class', 'interface'], '', $docComment);
59+
if ($docComment === $name) {
60+
continue;
61+
}
62+
63+
// We have found at lease one meaningful line in comment description
64+
return true;
65+
}
66+
67+
// Contains nothing but the tags
68+
if ($hasTags === true && $hasDescription === false) {
69+
return true;
70+
}
71+
72+
return false;
73+
}
74+
}

0 commit comments

Comments
 (0)