Chris@0: <?php
Chris@0: /**
Chris@0:  * Represents a PHP_CodeSniffer sniff for sniffing coding standards.
Chris@0:  *
Chris@0:  * PHP version 5
Chris@0:  *
Chris@0:  * @category  PHP
Chris@0:  * @package   PHP_CodeSniffer
Chris@0:  * @author    Greg Sherwood <gsherwood@squiz.net>
Chris@0:  * @author    Marc McIntyre <mmcintyre@squiz.net>
Chris@0:  * @copyright 2006-2014 Squiz Pty Ltd (ABN 77 084 670 600)
Chris@0:  * @license   https://github.com/squizlabs/PHP_CodeSniffer/blob/master/licence.txt BSD Licence
Chris@0:  * @link      http://pear.php.net/package/PHP_CodeSniffer
Chris@0:  */
Chris@0: 
Chris@0: /**
Chris@0:  * Represents a PHP_CodeSniffer sniff for sniffing coding standards.
Chris@0:  *
Chris@0:  * A sniff registers what token types it wishes to listen for, then, when
Chris@0:  * PHP_CodeSniffer encounters that token, the sniff is invoked and passed
Chris@0:  * information about where the token was found in the stack, and the
Chris@0:  * PHP_CodeSniffer file in which the token was found.
Chris@0:  *
Chris@0:  * @category  PHP
Chris@0:  * @package   PHP_CodeSniffer
Chris@0:  * @author    Greg Sherwood <gsherwood@squiz.net>
Chris@0:  * @author    Marc McIntyre <mmcintyre@squiz.net>
Chris@0:  * @copyright 2006-2014 Squiz Pty Ltd (ABN 77 084 670 600)
Chris@0:  * @license   https://github.com/squizlabs/PHP_CodeSniffer/blob/master/licence.txt BSD Licence
Chris@0:  * @version   Release: @package_version@
Chris@0:  * @link      http://pear.php.net/package/PHP_CodeSniffer
Chris@0:  */
Chris@0: interface PHP_CodeSniffer_Sniff
Chris@0: {
Chris@0: 
Chris@0: 
Chris@0:     /**
Chris@0:      * Registers the tokens that this sniff wants to listen for.
Chris@0:      *
Chris@0:      * An example return value for a sniff that wants to listen for whitespace
Chris@0:      * and any comments would be:
Chris@0:      *
Chris@0:      * <code>
Chris@0:      *    return array(
Chris@0:      *            T_WHITESPACE,
Chris@0:      *            T_DOC_COMMENT,
Chris@0:      *            T_COMMENT,
Chris@0:      *           );
Chris@0:      * </code>
Chris@0:      *
Chris@0:      * @return int[]
Chris@0:      * @see    Tokens.php
Chris@0:      */
Chris@0:     public function register();
Chris@0: 
Chris@0: 
Chris@0:     /**
Chris@0:      * Called when one of the token types that this sniff is listening for
Chris@0:      * is found.
Chris@0:      *
Chris@0:      * The stackPtr variable indicates where in the stack the token was found.
Chris@0:      * A sniff can acquire information this token, along with all the other
Chris@0:      * tokens within the stack by first acquiring the token stack:
Chris@0:      *
Chris@0:      * <code>
Chris@0:      *    $tokens = $phpcsFile->getTokens();
Chris@0:      *    echo 'Encountered a '.$tokens[$stackPtr]['type'].' token';
Chris@0:      *    echo 'token information: ';
Chris@0:      *    print_r($tokens[$stackPtr]);
Chris@0:      * </code>
Chris@0:      *
Chris@0:      * If the sniff discovers an anomaly in the code, they can raise an error
Chris@0:      * by calling addError() on the PHP_CodeSniffer_File object, specifying an error
Chris@0:      * message and the position of the offending token:
Chris@0:      *
Chris@0:      * <code>
Chris@0:      *    $phpcsFile->addError('Encountered an error', $stackPtr);
Chris@0:      * </code>
Chris@0:      *
Chris@0:      * @param PHP_CodeSniffer_File $phpcsFile The PHP_CodeSniffer file where the
Chris@0:      *                                        token was found.
Chris@0:      * @param int                  $stackPtr  The position in the PHP_CodeSniffer
Chris@0:      *                                        file's token stack where the token
Chris@0:      *                                        was found.
Chris@0:      *
Chris@0:      * @return void|int Optionally returns a stack pointer. The sniff will not be
Chris@0:      *                  called again on the current file until the returned stack
Chris@0:      *                  pointer is reached. Return (count($tokens) + 1) to skip
Chris@0:      *                  the rest of the file.
Chris@0:      */
Chris@0:     public function process(PHP_CodeSniffer_File $phpcsFile, $stackPtr);
Chris@0: 
Chris@0: 
Chris@0: }//end interface