From 33cf15c3597a67a2229ad5ff0e58920e32213a0a Mon Sep 17 00:00:00 2001 From: jrfnl Date: Thu, 27 Sep 2018 20:21:14 +0200 Subject: [PATCH] Initial commit / v 1.0.0 - Adds two rulesets for the polyfill libraries provided by Paragonie. - Adds README with basic installation and usage instructions. - Adds `composer.json` file which requires the PHPCompatibility standard and `dev` requires the DealerDirect PHPCS Composer plugin to install the standards for testing. - Adds two minimal PHP files to test the rulesets against. - Adds a Travis config to test the rulesets, validate the ruleset XML and the Composer configuration on each update. - Adds `.gitignore` to ignore the `vendor` directory and the `composer.lock` file. - Adds `.gitattributes` to keep release archives clean. - Adds `.github/issue_template.md` to try and prevent issues related to the generic PHPCompatibility standard from being opened in this repository. --- .gitattributes | 15 ++ .github/issue_template.md | 9 ++ .gitignore | 2 + .travis.yml | 50 ++++++ .../ruleset.xml | 20 +++ .../ruleset.xml | 148 ++++++++++++++++++ README.md | 103 +++++++++++- Test/ParagonieRandomCompatTest.php | 13 ++ Test/ParagonieSodiumCompatTest.php | 13 ++ composer.json | 31 ++++ 10 files changed, 403 insertions(+), 1 deletion(-) create mode 100644 .gitattributes create mode 100644 .github/issue_template.md create mode 100644 .gitignore create mode 100644 .travis.yml create mode 100644 PHPCompatibilityParagonieRandomCompat/ruleset.xml create mode 100644 PHPCompatibilityParagonieSodiumCompat/ruleset.xml create mode 100644 Test/ParagonieRandomCompatTest.php create mode 100644 Test/ParagonieSodiumCompatTest.php create mode 100644 composer.json diff --git a/.gitattributes b/.gitattributes new file mode 100644 index 0000000..e1a04bb --- /dev/null +++ b/.gitattributes @@ -0,0 +1,15 @@ +# +# Exclude these files from release archives. +# https://blog.madewithlove.be/post/gitattributes/ +# +/.gitattributes export-ignore +/.gitignore export-ignore +/.travis.yml export-ignore +/.github/ export-ignore +/Test/ export-ignore + +# +# Auto detect text files and perform LF normalization +# http://davidlaing.com/2012/09/19/customise-your-gitattributes-to-become-a-git-ninja/ +# +* text=auto diff --git a/.github/issue_template.md b/.github/issue_template.md new file mode 100644 index 0000000..61cf5a7 --- /dev/null +++ b/.github/issue_template.md @@ -0,0 +1,9 @@ + diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..3a9875b --- /dev/null +++ b/.gitignore @@ -0,0 +1,2 @@ +/vendor/ +composer.lock diff --git a/.travis.yml b/.travis.yml new file mode 100644 index 0000000..52512c7 --- /dev/null +++ b/.travis.yml @@ -0,0 +1,50 @@ +sudo: false + +dist: trusty + +cache: + apt: true + +language: php + +## Cache composer downloads. +cache: + directories: + - $HOME/.cache/composer/files + +matrix: + fast_finish: true + include: + - php: 7.2 + addons: + apt: + packages: + - libxml2-utils + - php: 5.4 + +before_install: + # Speed up build time by disabling Xdebug when its not needed. + - if [[ $COVERALLS_VERSION == "notset" ]]; then phpenv config-rm xdebug.ini || echo 'No xdebug config.'; fi + - export XMLLINT_INDENT=" " + - composer install + - vendor/bin/phpcs -i + +script: + - | + if [[ $TRAVIS_PHP_VERSION == "7.2" ]]; then + # Validate the xml files. + # @link http://xmlsoft.org/xmllint.html + xmllint --noout ./*/ruleset.xml + + # Check the code-style consistency of the xml files. + diff -B ./PHPCompatibilityParagonieRandomCompat/ruleset.xml <(xmllint --format "./PHPCompatibilityParagonieRandomCompat/ruleset.xml") + diff -B ./PHPCompatibilityParagonieSodiumCompat/ruleset.xml <(xmllint --format "./PHPCompatibilityParagonieSodiumCompat/ruleset.xml") + fi + + # Test the rulesets. + - vendor/bin/phpcs ./Test/ParagonieRandomCompatTest.php --standard=PHPCompatibilityParagonieRandomCompat --runtime-set testVersion 5.2 + - vendor/bin/phpcs ./Test/ParagonieSodiumCompatTest.php --standard=PHPCompatibilityParagonieSodiumCompat --runtime-set testVersion 5.3 + + # Validate the composer.json file. + # @link https://getcomposer.org/doc/03-cli.md#validate + - composer validate --no-check-all --strict diff --git a/PHPCompatibilityParagonieRandomCompat/ruleset.xml b/PHPCompatibilityParagonieRandomCompat/ruleset.xml new file mode 100644 index 0000000..4828cb7 --- /dev/null +++ b/PHPCompatibilityParagonieRandomCompat/ruleset.xml @@ -0,0 +1,20 @@ + + + PHPCompatibility ruleset for PHP_CodeSniffer which accounts for polyfills provided by the Paragonie random_compat library. + + + + + + + + + + + + + + + + + diff --git a/PHPCompatibilityParagonieSodiumCompat/ruleset.xml b/PHPCompatibilityParagonieSodiumCompat/ruleset.xml new file mode 100644 index 0000000..a0b189b --- /dev/null +++ b/PHPCompatibilityParagonieSodiumCompat/ruleset.xml @@ -0,0 +1,148 @@ + + + PHPCompatibility ruleset for PHP_CodeSniffer which accounts for polyfills provided by the Paragonie sodium_compat library. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/README.md b/README.md index 7a5e8fb..d3bf8db 100644 --- a/README.md +++ b/README.md @@ -1,2 +1,103 @@ +[![Latest Stable Version](https://poser.pugx.org/phpcompatibility/phpcompatibility-paragonie/v/stable.png)](https://packagist.org/packages/phpcompatibility/phpcompatibility-paragonie) +[![Latest Unstable Version](https://poser.pugx.org/phpcompatibility/phpcompatibility-paragonie/v/unstable.png)](https://packagist.org/packages/phpcompatibility/phpcompatibility-paragonie) +[![License](https://poser.pugx.org/phpcompatibility/phpcompatibility-paragonie/license.png)](https://github.com/PHPCompatibility/PHPCompatibilityParagonie/blob/master/LICENSE) +[![Build Status](https://travis-ci.org/PHPCompatibility/PHPCompatibilityParagonie.svg?branch=master)](https://travis-ci.org/PHPCompatibility/PHPCompatibilityParagonie) + # PHPCompatibilityParagonie -PHPCompatibility rulesets which can be included in projects using the Paragonie polyfill libraries + +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](https://github.com/PHPCompatibility/PHPCompatibility) by excluding back-fills and poly-fills which are provided by those libraries. + +Paragonie Polyfill Library | Corresponding PHPCompatibility Ruleset | Includes +--- | --- | --- +[`random_compat`](https://github.com/paragonie/random_compat) | `PHPCompatibilityParagonieRandomCompat` +[`sodium_compat`](https://github.com/paragonie/sodium_compat) | `PHPCompatibilityParagonieSodiumCompat` | `PHPCompatibilityParagonieRandomCompat` + +> Note: +> As the `sodium_compat` library has `random_compat` [as a dependency](https://github.com/paragonie/sodium_compat/blob/master/composer.json), 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. + + +## Requirements + +* [PHP_CodeSniffer](https://github.com/squizlabs/PHP_CodeSniffer). + * PHP 5.3+ for use with [PHP_CodeSniffer](https://github.com/squizlabs/PHP_CodeSniffer) 2.3.0+. + * PHP 5.4+ for use with [PHP_CodeSniffer](https://github.com/squizlabs/PHP_CodeSniffer) 3.0.2+. + + Use the latest stable release of PHP_CodeSniffer for the best results. + The minimum _recommended_ version of PHP_CodeSniffer is version 2.6.0. +* [PHPCompatibility](https://github.com/PHPCompatibility/PHPCompatibility) 9.0.0+. + + +## Installation instructions + +The only supported installation method is via [Composer](https://getcomposer.org/). + +If you don't have a Composer plugin installed to manage the `installed_paths` setting for PHP_CodeSniffer, run the following from the command-line: +```bash +composer require --dev dealerdirect/phpcodesniffer-composer-installer:^0.4.4 phpcompatibility/phpcompatibility-paragonie:* +composer install +``` + +If you already have a Composer PHP_CodeSniffer plugin installed, run: +```bash +composer require --dev phpcompatibility/phpcompatibility-paragonie:* +composer install +``` + +Next, run: +```bash +vendor/bin/phpcs -i +``` +If all went well, you will now see that the `PHPCompatibility`, `PHPCompatibilityParagonieRandomCompat` and `PHPCompatibilityParagonieSodiumCompat` standards are installed for PHP_CodeSniffer. + + +## How to use + +Now you can use the following commands to inspect the code in your project for PHP cross-version compatibility: +```bash +./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: +```bash +# 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](https://github.com/PHPCompatibility/PHPCompatibility#sniffing-your-code-for-compatibility-with-specific-php-versions) standard. + + +### Testing PHP files only + +By default PHP_CodeSniffer 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: +```bash +./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/copyleft/lesser.html + + +## Changelog + +### 1.0.0 - 2018-10-07 + +Initial release of PHPCompatibilityParagonie containing rulesets covering the `random_compat` and `sodium_compat` polyfill libraries. diff --git a/Test/ParagonieRandomCompatTest.php b/Test/ParagonieRandomCompatTest.php new file mode 100644 index 0000000..8c49d94 --- /dev/null +++ b/Test/ParagonieRandomCompatTest.php @@ -0,0 +1,13 @@ +