README

Using PHPCompatibilityParagonie, you can analyse the codebase of a project using either of the Paragonie polyfills, for PHP cross-version compatibility.

What's in this repo ?

Two rulesets for PHP_CodeSniffer to check for PHP cross-version compatibility issues in projects, while accounting for polyfills provided by the Paragonie polyfill libraries.

These rulesets prevent false positives from the PHPCompatibility standard by excluding back-fills and polyfills which are provided by those libraries.

Note

As the sodium_compat library has random_compat as a dependency, the PHPCompatibilityParagonieSodiumCompat ruleset includes the PHPCompatibilityParagonieRandomCompat ruleset.

In practice, this means that if your project uses both libraries, you just need to use the PHPCompatibilityParagonieSodiumCompat ruleset to prevent false positives from both.

Funding

This project needs funding.

The project team has spend thousands of hours creating and maintaining the PHPCompatibility packages. This is unsustainable without funding.

If you use PHPCompatibility, please fund this work by setting up a monthly contribution to the PHP_CodeSniffer Open Collective.

Requirements

• PHP > 5.4
• PHP_CodeSniffer >= 3.13.3. Use the latest stable release of PHP_CodeSniffer for the best results.
• PHPCompatibility 10.0.0+.

Installation instructions

The only supported installation method is via Composer.

Composer will automatically install the project dependencies and register the external rulesets with PHP_CodeSniffer using the Composer PHPCS plugin.

Run the following from the root of your project:

composer config allow-plugins.dealerdirect/phpcodesniffer-composer-installer true
composer require --dev phpcompatibility/phpcompatibility-paragonie:"^2.0@dev"

Next, run:

vendor/bin/phpcs -i

If all went well, you will now see that the PHPCompatibility, PHPCompatibilityParagonieRandomCompat and PHPCompatibilityParagonieSodiumCompat standards are installed for PHP_CodeSniffer.

Upgrade instructions

To upgrade this package, run the following command:

composer update --dev phpcompatibility/phpcompatibility-paragonie --with-dependencies

Tip

If you have a root requirement in your project for one of the packages used by this project, you may need to update with --with-all-dependencies instead.

How to use

You can now use the following commands to inspect the code in your project for PHP cross-version compatibility:

vendor/bin/phpcs -p . --standard=PHPCompatibilityParagonieRandomCompat

vendor/bin/phpcs -p . --standard=PHPCompatibilityParagonieSodiumCompat

By default, you will only receive notifications about deprecated and/or removed PHP features.

To get the most out of the PHPCompatibilityParagonie rulesets, you should specify a testVersion to check against. That will enable the checks for both deprecated/removed PHP features as well as the detection of code using new PHP features.

For example:

# For a project which should be compatible with PHP 5.3 up to and including PHP 7.0:
vendor/bin/phpcs -p . --standard=PHPCompatibilityParagonieRandomCompat --runtime-set testVersion 5.3-7.0

# For a project which should be compatible with PHP 5.4 and higher:
vendor/bin/phpcs -p . --standard=PHPCompatibilityParagonieSodiumCompat --runtime-set testVersion 5.4-

For more detailed information about setting the testVersion, see the README of the generic PHPCompatibility standard.

Testing PHP files only

By default PHP_CodeSniffer < 4.0 will analyse PHP, JavaScript and CSS files. As the PHPCompatibility sniffs only target PHP code, you can make the run slightly faster by telling PHP_CodeSniffer to only check PHP files, like so:

vendor/bin/phpcs -p . --standard=PHPCompatibilityParagonieRandomCompat --extensions=php --runtime-set testVersion 5.3-

License

All code within the PHPCompatibility organisation is released under the GNU Lesser General Public License (LGPL). For more information, visit https://www.gnu.org/licenses/lgpl-3.0.html.