PHPCSStandards/PHP_CodeSniffer 3.0.0a1

3.0.0a1 - 2016-07-20

on GitHub

This is the first alpha release of the 3.0.0 version, and is a large refactoring of the code base. It breaks backwards compatibility for all custom sniffs and custom reports. An upgrade guide for sniff and report developers is available here: https://github.com/PHPCSStandards/PHP_CodeSniffer/wiki/Version-3.0-Upgrade-Guide

Note: If you only use the built-in coding standards (such as PEAR or PSR2), or you have a custom ruleset.xml file that only makes use of the sniffs and reports distributed with PHP_CodeSniffer, you do not need to make any changes to use this alpha release.

PHP version change

This release changes the minimum PHP version from 5.1.2 to 5.4.0.

• Why not 5.6? Because the reality is that many developers have to work in corporate environments where the PHP version is maintained by the OS vendor. 5.6 and 7 are out of reach for a large number of developers working on big commercial applications, which is a place where PHPCS is of great benefit.
• Why not 5.3? Where 5.3 is available, 5.4 should be available through official OS repositories. The min PHP version for PHPCS will remain stable for some time, so an attempt has been made to pick a version that is hopefully available to the vast majority of developers while still providing new language features to PHPCS itself.

Installation

You can install PHP_CodeSniffer 3.0.0a1 via composer or PEAR, or download the PHAR files attached to these release notes. You can also clone the git repository directly and run PHPCS from there.

If you are using composer, you can use the 3.x-dev branch alias:

{
    "require-dev": {
        "squizlabs/php_codesniffer": "3.x-dev"
    }
}

If you are installing via PEAR, please first uninstall the existing PHP_CodeSniffer package before installing the new one:

pear uninstall PHP_CodeSniffer
pear install PHP_CodeSniffer-3.0.0a1

New features and core changes

• Added optional caching of results between runs (request #530)
  • Enable the cache by using the --cache command line argument
  • If you want the cache file written somewhere specific, use --cache=/path/to/cacheFile
  • Use the command "phpcs --config-set cache true" to turn caching on by default
  • Use the --no-cache command line argument to disable caching if it is being turned on automatically
• Add support for checking file in parallel (request #421)
  • Tell PHPCS how many files to check at once using the --parallel command line argument
  • To check 100 files at once, using --parallel=100
  • To disable parallel checking if it is being turned on automatically, use --parallel=1
  • Requires PHP to be compiled with the PCNTL package
• The default encoding has been changed from iso-8859-1 to utf-8 (request #760)
  • The --encoding command line argument still works, but you no longer have to set it to process files as utf-8
  • If encoding is being set to utf-8 in a ruleset or on the CLI, it can be safely removed
  • If the iconv PHP extension is not installed, standard non-multibyte aware functions will be used
• Added a new "code" report type to show a code snippet for each error (request #419)
  • The line containing the error is printed, along with 2 lines above and below it to show context
  • The location of the errors is underlined in the code snippet if you also use --colors
  • Use --report=code to generate this report
• Added support for custom filtering of the file list
  • Developers can write their own filter classes to perform custom filtering of the list before the run starts
  • Use the command line arg --filter=/path/to/filter.php to specify a filter to use
  • Extend \PHP_CodeSniffer\Filters\Filter to also support the core PHPCS extension and path filtering
  • Extend \PHP_CodeSniffer\Filters\ExactMatch to get the core filtering and the ability to use blacklists and whitelists
  • The included \PHP_CodeSniffer\Filters\GitModified filter is a good example of an ExactMatch filter
• Added support for only checking files that have been locally modified or added in a git repo
  • Use --filter=gitmodified to check these files
  • You still need to give PHPCS a list of files or directories in which to check
• Added automatic discovery of executable paths (request #571)
  • Thanks to Sergey Morozov for the patch
• You must now pass "-" on the command line to have PHPCS wait for STDIN
  • E.g., phpcs --standard=PSR2 -
  • You can still pipe content via STDIN as normal as PHPCS will see this and process it
  • But without the "-", PHPCS will throw an error if no content or files are passed to it
• All PHP errors generated by sniffs are caught, re-thrown as exceptions, and reported in the standard error reports
  • This should stop bugs inside sniffs causing infinite loops
  • Also stops invalid reports being produced as errors don't print to the screen directly
• Sniff codes are no longer optional
  • If a sniff throws and error or a warning, it must specify an internal code for that message
• The installed_paths config setting can now point directly to a standard
  • Previously, it had to always point to the directory in which the standard lives
• Multiple reports can now be specified using the --report command line argument
  • Report types are separated by commas
  • E.g., --report=full,summary,info
  • Previously, you had to use one argument for each report such as --report=full --report=summary --report=info
• You can now set the severity, message type, and exclude patterns for an entire sniff, category, or standard
  • Previously, this was only available for a single message
• You can now include a single sniff code in a ruleset instead of having to include an entire sniff
  • Including a sniff code will automatically exclude all other messages from that sniff
  • If the sniff is already included by an imported standard, set the sniff severity to 0 and include the specific message you want
• PHPCBF no longer uses patch
  • Files are now always overwritten
  • The --no-patch option has been removed
• Added a --basepath option to strip a directory from the front of file paths in output (request #470)
  • The basepath is absolute or relative to the current directory
  • E.g., to output paths relative to current dir in reports, use --basepath=.
• Ignore rules are now checked when using STDIN (request #733)
• Added an include-pattern tag to rulesets to include a sniff for specific files and folders only (request #656)
  • This is the exact opposite of the exclude-pattern tag
  • This option is only usable within sniffs, not globally like exclude-patterns are
• Added a new -m option to stop error messages from being recorded, which saves a lot of memory
  • PHPCBF always uses this setting to reduce memory as it never outputs error messages
  • Setting the $recordErrors member var inside custom report classes is no longer supported (use -m instead)
• Exit code 2 is now used to indicate fixable errors were found (request #930)
  • Exit code 3 is now used for general script execution errors
  • Exit code 1 is used to indicate that coding standard errors were found, but none are fixable
  • Exit code 0 is unchanged and continues to mean no coding standard errors found
• The included PHPCS standard has been removed
  • All rules are now found inside the phpcs.xml.dist file
  • Running "phpcs" without any arguments from a git clone will use this ruleset
• The included SVN pre-commit hook has been removed
  • Hooks for version control systems will no longer be maintained within the PHPCS project