1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
|
<?php
/**
*
* This file is part of the phpBB Forum Software package.
*
* @copyright (c) phpBB Limited <https://www.phpbb.com>
* @license GNU General Public License, version 2 (GPL-2.0)
*
* For full copyright and license information, please see
* the docs/CREDITS.txt file.
*
*/
use PHP_CodeSniffer\Files\File;
use PHP_CodeSniffer\Sniffs\Sniff;
/**
* Checks that each PHP source file contains a valid header as defined by the
* phpBB Coding Guidelines.
*
* @package code_sniffer
* @author Manuel Pichler <mapi@phpundercontrol.org>
*/
class phpbb_Sniffs_Commenting_FileCommentSniff implements Sniff
{
/**
* Returns an array of tokens this test wants to listen for.
*
* @return array
*/
public function register()
{
return array(T_OPEN_TAG);
}
/**
* Processes this test, when one of its tokens is encountered.
*
* @param 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): void
{
// We are only interested in the first file comment.
if ($stackPtr !== 0)
{
if ($phpcsFile->findPrevious(T_OPEN_TAG, $stackPtr - 1) !== false)
{
return;
}
}
// Fetch next non whitespace token
$tokens = $phpcsFile->getTokens();
$start = $phpcsFile->findNext(T_WHITESPACE, $stackPtr + 1, null, true);
// Skip empty files
if ($tokens[$start]['code'] === T_CLOSE_TAG)
{
return;
}
// Mark as error if this is not a doc comment
else if ($start === false || $tokens[$start]['code'] !== T_DOC_COMMENT_OPEN_TAG)
{
$phpcsFile->addError('Missing required file doc comment.', $stackPtr, 'MissingComment');
return;
}
// Find comment end token
$end = $tokens[$start]['comment_closer'];
// If there is no end, skip processing here
if ($end === false)
{
return;
}
// check comment lines without the first(/**) an last(*/) line
for ($token = $start + 1, $c = $end - 2; $token <= $c; ++$token)
{
// Check that each line starts with a '*'
if ($tokens[$token]['column'] === 1 && (($tokens[$token]['content'] !== '*' && $tokens[$token]['content'] !== ' ') || ($tokens[$token]['content'] === ' ' && $tokens[$token + 1]['content'] !== '*')))
{
$message = 'The file doc comment should not be indented.';
$phpcsFile->addWarning($message, $token, 'CommentIndented');
}
}
// Check that the first and last line is empty
// /**T_WHITESPACE
// (T_WHITESPACE)*T_WHITESPACE
// (T_WHITESPACE)* ...
// (T_WHITESPACE)*T_WHITESPACE
// T_WHITESPACE*/
if (!(($tokens[$start + 2]['content'] !== '*' && $tokens[$start + 4]['content'] !== '*') || ($tokens[$start + 3]['content'] !== '*' && $tokens[$start + 6]['content'] !== '*')))
{
$message = 'The first file comment line should be empty.';
$phpcsFile->addWarning($message, ($start + 1), 'CommentFirstNotEmpty');
}
if ($tokens[$end - 3]['content'] !== '*' && $tokens[$end - 6]['content'] !== '*')
{
$message = 'The last file comment line should be empty.';
$phpcsFile->addWarning($message, $end - 1, 'CommentLastNotEmpty');
}
//$this->processPackage($phpcsFile, $start, $tags);
//$this->processVersion($phpcsFile, $start, $tags);
$this->processCopyright($phpcsFile, $start, $tokens[$start]['comment_tags']);
$this->processLicense($phpcsFile, $start, $tokens[$start]['comment_tags']);
}
/**
* Checks that the tags array contains a valid package tag
*
* @param File $phpcsFile The context source file instance.
* @param integer The stack pointer for the first comment token.
* @param array(string=>array) $tags The found file doc comment tags.
*
* @return void
*/
protected function processPackage(File $phpcsFile, $ptr, $tags): void
{
if (!isset($tags['package']))
{
$message = 'Missing require @package tag in file doc comment.';
$phpcsFile->addError($message, $ptr, 'MissingTagPackage');
}
else if (preg_match('/^([\w]+)$/', $tags['package'][0]) === 0)
{
$message = 'Invalid content found for @package tag.';
$phpcsFile->addWarning($message, $tags['package'][1], 'InvalidTagPackage');
}
}
/**
* Checks that the tags array contains a valid version tag
*
* @param File $phpcsFile The context source file instance.
* @param integer The stack pointer for the first comment token.
* @param array(string=>array) $tags The found file doc comment tags.
*
* @return void
*/
protected function processVersion(File $phpcsFile, $ptr, $tags): void
{
if (!isset($tags['version']))
{
$message = 'Missing require @version tag in file doc comment.';
$phpcsFile->addError($message, $ptr, 'MissingTagVersion');
}
else if (preg_match('/^\$Id:[^\$]+\$$/', $tags['version'][0]) === 0)
{
$message = 'Invalid content found for @version tag, use "$Id: $".';
$phpcsFile->addError($message, $tags['version'][1], 'InvalidTagVersion');
}
}
/**
* Checks that the tags array contains a valid copyright tag
*
* @param File $phpcsFile The context source file instance.
* @param integer The stack pointer for the first comment token.
* @param array(string=>array) $tags The found file doc comment tags.
*
* @return void
*/
protected function processCopyright(File $phpcsFile, $ptr, $tags): void
{
$copyright = '(c) phpBB Limited <https://www.phpbb.com>';
$tokens = $phpcsFile->getTokens();
foreach ($tags as $tag)
{
if ($tokens[$tag]['content'] === '@copyright')
{
if ($tokens[$tag + 2]['content'] !== $copyright)
{
$message = 'Invalid content found for the first @copyright tag, use "' . $copyright . '".';
$phpcsFile->addError($message, $tags['copyright'][0][1], 'InvalidTagCopyright');
}
return;
}
}
$message = 'Missing require @copyright tag in file doc comment.';
$phpcsFile->addError($message, $ptr, 'MissingTagCopyright');
}
/**
* Checks that the tags array contains a valid license tag
*
* @param File $phpcsFile The context source file instance.
* @param integer The stack pointer for the first comment token.
* @param array(string=>array) $tags The found file doc comment tags.
*
* @return void
*/
protected function processLicense(File $phpcsFile, $ptr, $tags): void
{
$license = 'GNU General Public License, version 2 (GPL-2.0)';
$tokens = $phpcsFile->getTokens();
$found = false;
foreach ($tags as $tag)
{
if ($tokens[$tag]['content'] === '@license')
{
if ($found)
{
$message = 'It must be only one @license tag in file doc comment.';
$phpcsFile->addError($message, $ptr, 'MultiTagVersion');
}
$found = true;
if ($tokens[$tag + 2]['content'] !== $license)
{
$message = 'Invalid content found for @license tag, use "' . $license . '".';
$phpcsFile->addError($message, $tags['license'][0][1], 'InvalidTagLicense');
}
}
}
if (!$found)
{
$message = 'Missing require @license tag in file doc comment.';
$phpcsFile->addError($message, $ptr, 'MissingTagLicense');
}
}
}
|
