1<?php
2/**
3 * Represents a PHP_CodeSniffer sniff for sniffing coding standards.
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 * Represents a PHP_CodeSniffer sniff for sniffing coding standards.
18 *
19 * A sniff registers what token types it wishes to listen for, then, when
20 * PHP_CodeSniffer encounters that token, the sniff is invoked and passed
21 * information about where the token was found in the stack, and the
22 * PHP_CodeSniffer file in which the token was found.
23 *
24 * @category  PHP
25 * @package   PHP_CodeSniffer
26 * @author    Greg Sherwood <gsherwood@squiz.net>
27 * @author    Marc McIntyre <mmcintyre@squiz.net>
28 * @copyright 2006-2014 Squiz Pty Ltd (ABN 77 084 670 600)
29 * @license   https://github.com/squizlabs/PHP_CodeSniffer/blob/master/licence.txt BSD Licence
30 * @version   Release: @package_version@
31 * @link      http://pear.php.net/package/PHP_CodeSniffer
32 */
33interface PHP_CodeSniffer_Sniff
34{
35
36
37    /**
38     * Registers the tokens that this sniff wants to listen for.
39     *
40     * An example return value for a sniff that wants to listen for whitespace
41     * and any comments would be:
42     *
43     * <code>
44     *    return array(
45     *            T_WHITESPACE,
46     *            T_DOC_COMMENT,
47     *            T_COMMENT,
48     *           );
49     * </code>
50     *
51     * @return int[]
52     * @see    Tokens.php
53     */
54    public function register();
55
56
57    /**
58     * Called when one of the token types that this sniff is listening for
59     * is found.
60     *
61     * The stackPtr variable indicates where in the stack the token was found.
62     * A sniff can acquire information this token, along with all the other
63     * tokens within the stack by first acquiring the token stack:
64     *
65     * <code>
66     *    $tokens = $phpcsFile->getTokens();
67     *    echo 'Encountered a '.$tokens[$stackPtr]['type'].' token';
68     *    echo 'token information: ';
69     *    print_r($tokens[$stackPtr]);
70     * </code>
71     *
72     * If the sniff discovers an anomaly in the code, they can raise an error
73     * by calling addError() on the PHP_CodeSniffer_File object, specifying an error
74     * message and the position of the offending token:
75     *
76     * <code>
77     *    $phpcsFile->addError('Encountered an error', $stackPtr);
78     * </code>
79     *
80     * @param PHP_CodeSniffer_File $phpcsFile The PHP_CodeSniffer file where the
81     *                                        token was found.
82     * @param int                  $stackPtr  The position in the PHP_CodeSniffer
83     *                                        file's token stack where the token
84     *                                        was found.
85     *
86     * @return void|int Optionally returns a stack pointer. The sniff will not be
87     *                  called again on the current file until the returned stack
88     *                  pointer is reached. Return (count($tokens) + 1) to skip
89     *                  the rest of the file.
90     */
91    public function process(PHP_CodeSniffer_File $phpcsFile, $stackPtr);
92
93
94}//end interface
95