This package offers the following features:
Normally to use the latest version of PHP_CodeSniffer native utility functions, you would have to raise the minimum requirements of your external PHPCS standard.
Now you won't have to anymore. This package allows you to use the latest version of those utility functions in all PHP_CodeSniffer versions from PHPCS 2.6.0 and up.
These classes take most of the heavy lifting away for some frequently occurring sniff types.
Collections of related tokens often-used and needed for sniffs.
These are additional "token groups" to compliment the ones available through the PHPCS native
Whether you need to split an
array into the individual items, are trying to determine which variables are being assigned to in a
list() or are figuring out whether a function has a DocBlock, PHPCSUtils has got you covered!
Includes improved versions of the PHPCS native utility functions and plenty of new utility functions.
These functions are, of course, compatible with PHPCS 2.6.0 up to PHPCS
UtilityMethodTestCase class to support testing of your utility methods written for PHP_CodeSniffer.
Compatible with both PHPCS 2.x as well as 3.x. Supports PHPUnit 4.x up to 9.x.
PHPCS23Utils standard which allows sniffs to work in both PHPCS 2.x and 3.x, as well as a few helper functions for external standards which still want to support both PHP_CodeSniffer 2.x as well as 3.x.
To see detailed information about all the available abstract sniffs, utility functions and PHPCS helper functions, have a read through the extensive documentation.
If your external PHP_CodeSniffer standard only supports Composer-based installs and has a minimum PHPCS requirement of PHP_CodeSniffer 3.1.0, integrating PHPCSUtils is pretty straight forward.
Run the following from the root of your external PHPCS standard's project:
composer require phpcsstandards/phpcsutils:"^1.0"
No further action needed. You can start using all the utility functions, abstract sniff classes and other features of PHPCSUtils straight away.
The PHPCSUtils package includes the DealerDirect Composer PHPCS plugin.
This plugin will automatically register PHPCSUtils (and your own external standard) with PHP_CodeSniffer, so you and your users don't have to worry about this anymore.
Note: if your end-user installation instructions include instructions on adding a Composer PHPCS plugin or on manually registering your standard with PHPCS using the
--config-set installed_pathscommand, you can remove those instructions as they are no longer needed.
If your unit tests use the PHP_CodeSniffer native unit test suite, all is good.
If you have your own unit test suite to test your sniffs, make sure to load the Composer
vendor/autoload.php file in your PHPUnit bootstrap file or as the PHPUnit bootstrap file.
If you intend to use the test utilities provided in the
PHPCSUtils/TestUtils directory, make sure you also load the
vendor/phpcsstandards/phpcsutils/phpcsutils-autoload.php file in your PHPUnit bootstrap file.
Follow the above instructions for use with PHPCS 3.x.
In addition to that, add the following to the
ruleset.xml file of your standard(s):
<!-- Make the utility functions available in PHPCS 2.x --> <rule ref="PHPCS23Utils"/>
PHPCS23Utils"standard" does not add any real sniffs, it only makes sure that the Utility functions will work in PHPCS 2.x as well.
If your standard supports both PHPCS 2.x as well as 3.x, you are bound to already have a PHPUnit
bootstrap.php file in place.
To allow the unit tests to find the relevant files for PHPCSUtils, make sure that the bootstrap loads both the Composer
vendor/autoload.php file, as well as the
A: As PHPCSUtils is registered with PHPCS as an external standard and PHPCSUtils complies with the naming requirements of PHPCS, the PHPCS native autoloader will automatically take care of loading the classes used from PHPCSUtils.
A: All the
PHPCS23Utils standard does is load the
PHPCS 3.x uses namespaces, while PHPCS 2.x does not. The
phpcsutils-autoload.php file creates
class_alias-es for the most commonly used PHPCS classes, including all PHPCS classes used by PHPCSUtils. That way, both your external standard as well as PHPCSUtils can refer to the PHPCS 3.x class names and the code will still work in PHPCS 2.x.
A: The backfill for PHP 7.4 numeric literals with underscores in PHP_CodeSniffer 3.5.3 is broken and there is no way to reliably provide support for anything to do with numbers or
T_STRING tokens when using PHP_CodeSniffer 3.5.3 as the tokens returned by the tokenizer are unpredictable and unreliable.
The backfill was fixed in PHP_CodeSniffer 3.5.4.
A: Well, the arrow function backfill which was added in PHPCS 3.5.3 is still causing problems. In a very limited set of circumstances, it will even hang the Tokenizer. A fix for one particular such problem has been committed to
master, but is not (yet) in a released version. It is expected to be released in PHP_CodeSniffer 3.5.6.
As the Tokenizer hanging is a problem unrelated to PHPCSUtils and not something which can be mitigated from within PHPCSUtils in any conceivable way, PHPCSUtils won't block installation in combination with PHPCS 3.5.4 and 3.5.5.
There are several other issues which can not be worked around, like scope closers being set incorrectly and throwing the scope setting off for the rest of the file, so not withstanding that PHPCSUtils can work around a lot of issues, it is still highly recommended to advise your end-users to always use the latest version of PHPCS for the most reliable results.
A: No. PHPCSUtils will only work for those sniffs which explicitly use the PHPCSUtils functionality.
If your standard includes both PHPCS native sniffs as well as your own sniffs, your own sniffs can benefit from the back-compat layer offered by PHPCSUtils, as well as from the additional utility functions. However, the PHPCS native sniffs will not receive those benefits, as PHPCS itself does not use PHPCSUtils.
A: JS/CSS support will be removed from PHP_CodeSniffer in PHPCS 4.x. While at this time, some of the utilies may work with JS/CSS files, PHPCSUtils does not offer formal support for JS/CSS sniffing with PHP_CodeSniffer and will stop any existing support once PHPCS 4.x has been released.
A: No. The UTF-8 file encoding is the only officially supported encoding. Support for other encodings may incidentally work, but is not officially supported.
It is recommended to advise your users to save their files as UTF-8 encoded for the best results.
PHP_CodeSniffer 3.x will default to UTF-8 as the expected file encoding.
If your standard supports PHP_CodeSniffer 2.x, it is recommended to set the expected encoding in the ruleset to
utf-8, like so:
<arg name="encoding" value="utf-8"/> or to advise users to use the CLI option
Pro-tip: if you want to prevent the fatal error and show a friendlier error message instead, add
<rule ref="PHPCSUtils"/>to your standard's
With that in place, PHP_CodeSniffer will show a "ERROR: the "PHPCSUtils" coding standard is not installed." message if PHPCSUtils is missing as soon as the ruleset loading is finished.
Pro-tip: provide upgrade instructions for your end-users. For Composer-based installs, those should look like this:That way, when the user updates your coding standards package, they will automatically also update PHPCSUtils.
composer update your/cs-package --with-dependencies
Contributions to this project are welcome. Clone the repo, branch off from
develop, make your changes, commit them and send in a pull request.
If you are unsure whether the changes you are proposing would be welcome, please open an issue first to discuss your proposal.
This code is released under the GNU Lesser General Public License (LGPLv3).