PHPCSUtils

Features

PHPCSUtils is a set of utilities to aid developers of sniffs for PHP_CodeSniffer (or “PHPCS” for short).

This package offers the following features:

An ever-growing number of utility functions for use with PHP_CodeSniffer

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 compatible with PHPCS 3.10.0 up to PHPCS master.

A collection of static properties and methods for often-used token groups

Collections of related tokens often-used and needed for sniffs. These are additional “token groups” to compliment the ones available through the PHPCS native PHP_CodeSniffer\Util\Tokens class.

Several abstract sniff classes which your sniffs can extend

These classes take most of the heavy lifting away for some frequently occurring sniff types.

Test utilities

An abstract UtilityMethodTestCase class to support testing of your utility methods written for PHP_CodeSniffer. Supports PHPUnit 4.x up to 9.x.

Use the latest version of PHP_CodeSniffer native utility functions

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 3.10.0 and up.

Fully documented

To see detailed information about all the available abstract sniffs, utility functions and PHPCS helper functions, have a read through the extensive documentation.

Minimum Requirements

PHP 5.4 or higher.
PHP_CodeSniffer 3.10.0+.
Recommended PHP extensions for optimal functionality:
- PCRE with Unicode support (normally enabled by default)

Integrating PHPCSUtils in your external PHPCS standard

Composer-based

If your external PHP_CodeSniffer standard only supports Composer-based installs, integrating PHPCSUtils is pretty straight forward.

Run the following from the root of your external PHPCS standard’s project:

composer config allow-plugins.dealerdirect/phpcodesniffer-composer-installer true
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 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_paths command, you can remove those instructions as they are no longer needed.

As of Composer 2.2, Composer will ask for permission to allow the Composer PHPCS plugin to execute code. For the plugin to be functional, permission needs to be granted. This can be done ahead of time by instructing your users to run the following command before installing your standard:
composer config allow-plugins.dealerdirect/phpcodesniffer-composer-installer true

Running your unit tests

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.

Frequently Asked Questions

Q: How does this all work without an external standard needing to register an autoloader?

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.

Q: Does using PHPCSUtils have any effect on the PHPCS native sniffs?

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.

Q: Do the utilities work with javascript/CSS files?

A: JS/CSS support will be removed from PHP_CodeSniffer in PHPCS 4.x. While at this time, some of the utilities 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.

Q: Are all file encodings supported?

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.

Note: PHP_CodeSniffer 3.x defaults to UTF-8 as the expected file encoding.

Potential Support Questions from your End-Users

Q: A user reports a fatal “class not found” error for a class from PHPCSUtils

Check that the version of PHPCSUtils the user has installed complies with the minimum version of PHPCSUtils your standard requires. If not, they will need to upgrade.
If the version is correct, this indicates that the end-user does not have PHPCSUtils installed and/or registered with PHP_CodeSniffer.
- Please review your standard’s installation instructions to make sure that PHPCSUtils will be installed when those are followed.
- Inform the user to install PHPCSUtils and register it with PHP_CodeSniffer.

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 ruleset.xml file.

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:
composer update your/cs-package --with-[all-]dependencies
That way, when the user updates your coding standards package, they will automatically also update PHPCSUtils.

Contributing

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.

License

This code is released under the GNU Lesser General Public License (LGPLv3).