PHP_CodeSniffer 2.0.0 released05 Dec
Nineteen months ago, I started work on a project to allow PHP_CodeSniffer to fix the problems that it finds. Doing this required a lot of changes to the core classes, a lot of iteration and refactoring of the fixing and testing code, and an enormous amount of time and testing across many PHP projects to ensure I am confident enough to release something that actually modifies code. I could keep writing unit tests forever, but I've finally got to a point where I am happy to release this first version of the PHP Code Beautifier and Fixer (PHPCBF), for when you just can't be bothered fixing coding standard errors yourself.
I originally started with a goal of being able to fix the most commonly found errors when checking PHP projects using the PSR2 coding standard, but I expanded that goal to include all coding standards (including custom standards) and supported file types (PHP, JS and CSS). So as of version 2.0.0, when you run PHP_CodeSniffer and get your standard report of the errors found, you will now be able to see which of those errors can be automatically corrected by PHPCBF. Sample report output can be seen on the wiki: https://github.com/squizlabs/PHP_CodeSniffer/wiki/Fixing-Errors-Automatically
Custom Coding Standards
If you have a custom coding standard that uses the sniffs included with PHP_CodeSniffer, you will find that many of the errors your standard finds are already fixable with PHPCBF. PHP_CodeSniffer comes with just over 600 unique errors and PHPCBF is able to fix just over half of those. The rest of the errors are almost entirely made up of things that cannot be automatically fixed, such as variable names and changes to comparison operators.
If you have your own custom sniffs, you are able to add auto-fixing code to them using the new auto-fixing tools built into PHP_CodeSniffer. You have access to all the normal token-based functions you are used to, as well as some new fixer-specific functions to do things like replacing token content and adding content and newlines to tokens. PHPCBF is also able to group a set of changes so that they are all applied or rejected together, detect sniffs trying to fix the same piece of code in the same run, and detect and resolve conflicting changes that are being applied.
The Diff Report
Along with the new PHPCBF script, PHP_CodeSniffer adds a new report type; the diff report. If you don't like the idea of a script fixing errors automatically, you can instead ask PHP_CodeSniffer to output a diff of the fixes that it would make using the command line argument --report=diff. If you like what you see, you can simply change the phpcs command to phpcbf, leave all the command line options the same, and let PHPCBF patch your files.
Version 2.0.0 brings a lot more changes that just auto-fixing, including:
- a completely rewritten comment parser that is design to allow for auto-fixing (see https://www.squizlabs.com/php-codesniffer/2.0.0a1-released)
- a new information report to show you how your code is written rather than if it conforms to a standard (see https://github.com/squizlabs/PHP_CodeSniffer/wiki/Reporting#printing-an-information-report)
- the ability to set command line arguments in ruleset.xml files (see https://github.com/squizlabs/PHP_CodeSniffer/wiki/Annotated-ruleset.xml#the-annotated-sample-file)
- the ability to create your own custom reporting classes and use them with PHP_CodeSniffer
- distribution of PHPCS and PHPCBF as phar files
- support for running on HHVM
- detection of minified CSS and JS files
So many developers have helped test this auto-fixing code over the last year and half. More than twenty developers have directly contributed code to make the auto-fixing more accurate and more still have reported bugs to help diagnose issues with the fixing.
But I'd like to send special thanks to Alexander Obuhovich (@aik099 on Github and Twitter) for both testing PHPCBF and for being so active on Github issues and PRs, and to the developers working on the WordPress coding standards (https://github.com/WordPress-Coding-Standards/WordPress-Coding-Standards) for working with me to find solutions for running and testing complex custom coding standards and for trying out the auto-fixing code in their standard.
I've also released version 1.5.6 today and I'm keeping the 1.5 branch around for a little while longer to make it easier to upgrade to 2.0, especially for developers who need to change custom coding standards. If you have having problems with the 2.0 version, please use 1.5.6 in the meantime.