1<?php
2/**
3 * Squiz_Sniffs_PHP_CommentedOutCodeSniff.
4 *
5 * PHP version 5
6 *
7 * @category  PHP
8 * @package   PHP_CodeSniffer
9 * @author    Greg Sherwood <gsherwood@squiz.net>
10 * @author    Marc McIntyre <mmcintyre@squiz.net>
11 * @copyright 2006-2014 Squiz Pty Ltd (ABN 77 084 670 600)
12 * @license   https://github.com/squizlabs/PHP_CodeSniffer/blob/master/licence.txt BSD Licence
13 * @link      http://pear.php.net/package/PHP_CodeSniffer
14 */
15
16/**
17 * Squiz_Sniffs_PHP_CommentedOutCodeSniff.
18 *
19 * Warn about commented out code.
20 *
21 * @category  PHP
22 * @package   PHP_CodeSniffer
23 * @author    Greg Sherwood <gsherwood@squiz.net>
24 * @author    Marc McIntyre <mmcintyre@squiz.net>
25 * @copyright 2006-2014 Squiz Pty Ltd (ABN 77 084 670 600)
26 * @license   https://github.com/squizlabs/PHP_CodeSniffer/blob/master/licence.txt BSD Licence
27 * @version   Release: @package_version@
28 * @link      http://pear.php.net/package/PHP_CodeSniffer
29 */
30class Squiz_Sniffs_PHP_CommentedOutCodeSniff implements PHP_CodeSniffer_Sniff
31{
32
33    /**
34     * A list of tokenizers this sniff supports.
35     *
36     * @var array
37     */
38    public $supportedTokenizers = array(
39                                   'PHP',
40                                   'CSS',
41                                  );
42
43    /**
44     * If a comment is more than $maxPercentage% code, a warning will be shown.
45     *
46     * @var int
47     */
48    public $maxPercentage = 35;
49
50
51    /**
52     * Returns an array of tokens this test wants to listen for.
53     *
54     * @return array
55     */
56    public function register()
57    {
58        return array(T_COMMENT);
59
60    }//end register()
61
62
63    /**
64     * Processes this test, when one of its tokens is encountered.
65     *
66     * @param PHP_CodeSniffer_File $phpcsFile The file being scanned.
67     * @param int                  $stackPtr  The position of the current token
68     *                                        in the stack passed in $tokens.
69     *
70     * @return void
71     */
72    public function process(PHP_CodeSniffer_File $phpcsFile, $stackPtr)
73    {
74        $tokens = $phpcsFile->getTokens();
75
76        // Process whole comment blocks at once, so skip all but the first token.
77        if ($stackPtr > 0 && $tokens[$stackPtr]['code'] === $tokens[($stackPtr - 1)]['code']) {
78            return;
79        }
80
81        // Ignore comments at the end of code blocks.
82        if (substr($tokens[$stackPtr]['content'], 0, 6) === '//end ') {
83            return;
84        }
85
86        $content = '';
87        if ($phpcsFile->tokenizerType === 'PHP') {
88            $content = '<?php ';
89        }
90
91        for ($i = $stackPtr; $i < $phpcsFile->numTokens; $i++) {
92            if ($tokens[$stackPtr]['code'] !== $tokens[$i]['code']) {
93                break;
94            }
95
96            /*
97                Trim as much off the comment as possible so we don't
98                have additional whitespace tokens or comment tokens
99            */
100
101            $tokenContent = trim($tokens[$i]['content']);
102
103            if (substr($tokenContent, 0, 2) === '//') {
104                $tokenContent = substr($tokenContent, 2);
105            }
106
107            if (substr($tokenContent, 0, 1) === '#') {
108                $tokenContent = substr($tokenContent, 1);
109            }
110
111            if (substr($tokenContent, 0, 3) === '/**') {
112                $tokenContent = substr($tokenContent, 3);
113            }
114
115            if (substr($tokenContent, 0, 2) === '/*') {
116                $tokenContent = substr($tokenContent, 2);
117            }
118
119            if (substr($tokenContent, -2) === '*/') {
120                $tokenContent = substr($tokenContent, 0, -2);
121            }
122
123            if (substr($tokenContent, 0, 1) === '*') {
124                $tokenContent = substr($tokenContent, 1);
125            }
126
127            $content .= $tokenContent.$phpcsFile->eolChar;
128        }//end for
129
130        $content = trim($content);
131
132        if ($phpcsFile->tokenizerType === 'PHP') {
133            $content .= ' ?>';
134        }
135
136        // Quite a few comments use multiple dashes, equals signs etc
137        // to frame comments and licence headers.
138        $content = preg_replace('/[-=*]+/', '-', $content);
139
140        // Because we are not really parsing code, the tokenizer can throw all sorts
141        // of errors that don't mean anything, so ignore them.
142        $oldErrors = ini_get('error_reporting');
143        ini_set('error_reporting', 0);
144        try {
145            $stringTokens = PHP_CodeSniffer_File::tokenizeString($content, $phpcsFile->tokenizer, $phpcsFile->eolChar);
146        } catch (PHP_CodeSniffer_Exception $e) {
147            // We couldn't check the comment, so ignore it.
148            ini_set('error_reporting', $oldErrors);
149            return;
150        }
151
152        ini_set('error_reporting', $oldErrors);
153
154        $emptyTokens = array(
155                        T_WHITESPACE              => true,
156                        T_STRING                  => true,
157                        T_STRING_CONCAT           => true,
158                        T_ENCAPSED_AND_WHITESPACE => true,
159                        T_NONE                    => true,
160                        T_COMMENT                 => true,
161                       );
162
163        $numTokens = count($stringTokens);
164
165        /*
166            We know what the first two and last two tokens should be
167            (because we put them there) so ignore this comment if those
168            tokens were not parsed correctly. It obviously means this is not
169            valid code.
170        */
171
172        // First token is always the opening PHP tag.
173        if ($stringTokens[0]['code'] !== T_OPEN_TAG) {
174            return;
175        }
176
177        // Last token is always the closing PHP tag, unless something went wrong.
178        if (isset($stringTokens[($numTokens - 1)]) === false
179            || $stringTokens[($numTokens - 1)]['code'] !== T_CLOSE_TAG
180        ) {
181            return;
182        }
183
184        // Second last token is always whitespace or a comment, depending
185        // on the code inside the comment.
186        if ($phpcsFile->tokenizerType === 'PHP'
187            && isset(PHP_CodeSniffer_Tokens::$emptyTokens[$stringTokens[($numTokens - 2)]['code']]) === false
188        ) {
189            return;
190        }
191
192        $numComment  = 0;
193        $numPossible = 0;
194        $numCode     = 0;
195
196        for ($i = 0; $i < $numTokens; $i++) {
197            if (isset($emptyTokens[$stringTokens[$i]['code']]) === true) {
198                // Looks like comment.
199                $numComment++;
200            } else if (in_array($stringTokens[$i]['code'], PHP_CodeSniffer_Tokens::$comparisonTokens) === true
201                || in_array($stringTokens[$i]['code'], PHP_CodeSniffer_Tokens::$arithmeticTokens) === true
202                || $stringTokens[$i]['code'] === T_GOTO_LABEL
203            ) {
204                // Commented out HTML/XML and other docs contain a lot of these
205                // characters, so it is best to not use them directly.
206                $numPossible++;
207            } else {
208                // Looks like code.
209                $numCode++;
210            }
211        }
212
213        // We subtract 3 from the token number so we ignore the start/end tokens
214        // and their surrounding whitespace. We take 2 off the number of code
215        // tokens so we ignore the start/end tokens.
216        if ($numTokens > 3) {
217            $numTokens -= 3;
218        }
219
220        if ($numCode >= 2) {
221            $numCode -= 2;
222        }
223
224        $percentCode = ceil((($numCode / $numTokens) * 100));
225        if ($percentCode > $this->maxPercentage) {
226            // Just in case.
227            $percentCode = min(100, $percentCode);
228
229            $error = 'This comment is %s%% valid code; is this commented out code?';
230            $data  = array($percentCode);
231            $phpcsFile->addWarning($error, $stackPtr, 'Found', $data);
232        }
233
234    }//end process()
235
236
237}//end class
238