Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add the base rulesets #7

Merged
merged 6 commits into from
Dec 26, 2019
Merged

Add the base rulesets #7

merged 6 commits into from
Dec 26, 2019

Conversation

jrfnl
Copy link
Member

@jrfnl jrfnl commented Dec 26, 2019

This PR adds the base rulesets for PHPCSUtils.

It also puts QA in place to:

  • Validate the ruleset XML files and verify code style compliance for them.
  • Lint PHP files, as the first PHP files are now being introduced into the repo.
  • Check the code style of the PHP code.

Commit details:

PHPCSUtils: add the ruleset file

This will allow PHPCS to recognize PHPCSUtils as if it were an external PHPCS standard and handle the autoloading of all PHPCSUtils files automatically when using PHPCS 3+.

External standards using PHPCSUtils don't even need to add <rule ref="PHPCSUtils"/> to their own ruleset.
All that is needed is for the PHPCSUtils standard to be in the PHPCS installed_paths which - for Composer based installs - will automatically be taken care of by the DealerDirect Composer PHPCS plugin which is a required dependency for this package.

PHPCSUtils: add an (optional) autoloader

... for external standards which have their own test suite.

In PHPCS > 3.0.2+, when using the PHPCS native test suite, the files from PHPCSUtils will automatically load correctly.

However, when using a custom test suite, this will generally not be the case.
Requiring the phpcsutils-autoload.php file in the test runner bootstrap file will fix this.

Alternatively, if only Composer-based installs are supported, loading the vendor/autoload.php file generated by Composer should also fix this.

Notes:

PHPCS23Utils: add support for PHPCS 2.x

This commit is two-fold:

  1. It enhances the phpcsutils-autoload.php file to contain class aliases to translate the relevant PHPCS 3.x class names to PHPCS 2.x class names which, in effect, allows for the PHPCSUtils utilities to be used in both PHPCS 2.x as well as PHPCS 3.x.

  2. It adds a PHPCS23Utils ruleset with one PHPCS23Utils.Load.LoadUtils sniff.
    The only thing this standard does is trigger the PHPCSUtils autoload file in PHPCS 2.x.

This standard will not include any utilities or real sniffs. It is just in place to enable support for PHPCS 2.x in an as-simple-as-possible manner.

🔧 QA: lint the ruleset XML files

🔧 QA: lint PHP files in this repo

🔧 QA: add code style check for the code in this repo

This:

  • Adds a custom PHPCS ruleset which uses the PHPCSDev ruleset to check the code style of code in this repo, with a few, very select, exclusions.
  • Adds convenience scripts to the composer.json file to check the code of the repo.
  • And allows for individual developers to overload the phpcs.xml.dist file by ignoring the typical overload files.

Important notes:

  1. The compose require is done directly in the Composer script rather than in the require-dev section as the PHPCS requirements for the PHPCSDevTools package can conflict with the PHPCS requirements of this package.

The CS check for this package should always be run on a recent PHPCS version to get the benefit of new sniffs, while the Utils themselves are - and should be - compatible with a wider range of PHPCS versions.

  1. Using the above "trick" runs into issues when trying to remove the package on Travis due to some phantom uncommitted changes in the vendor/phpcstandards/phpcsdevtools directory. So, a separate script is used for Travis which doesn't composer remove of PHPCSDevTools.

  2. For the time being - until v 1.0.0 has been tagged for the PHPCSDevTools package -, the require will use the dev-develop branch of PHPCSDevTools.

Also, the composer validate check doesn't need to be run on every build. Running it on just one build is sufficient, so moving it to the sniff stage.

This will allow PHPCS to recognize PHPCSUtils as if it were an external PHPCS standard and handle the autoloading of all PHPCSUtils files automatically when using PHPCS 3+.

External standards using PHPCSUtils don't even need to add `<rule ref="PHPCSUtils"/>` to their own ruleset.
All that is needed is for the PHPCSUtils standard to be in the PHPCS `installed_paths` which - for Composer based installs - will automatically be taken care of by the DealerDirect Composer PHPCS plugin which is a required dependency for this package.
... for external standards which have their own test suite.

In PHPCS > 3.0.2+, when using the PHPCS native test suite, the files from PHPCSUtils will automatically load correctly.

However, when using a custom test suite, this will generally not be the case.
Requiring the `phpcsutils-autoload.php` file in the test runner bootstrap file will fix this.

Alternatively, if only Composer-based installs are supported, loading the `vendor/autoload.php` file generated by Composer should also fix this.

Notes:
* The file is named `phpcsutils-autoload.php` instead of `autoload.php` to prevent potential confusion with other autoload files.
    Also see: squizlabs/PHP_CodeSniffer 2751
* The autoloader definition is wrapped within a constant check to prevent conflicts/the autoloader from being registered multiple times, when several external PHPCS standards each use PHPCSUtils.
This commit is two-fold:

1. It enhances the `phpcsutils-autoload.php` file to contain class aliases to translate the relevant PHPCS 3.x class names to PHPCS 2.x class names which, in effect, allows for the PHPCSUtils utilities to be used in both PHPCS 2.x as well as PHPCS 3.x.

2. It adds a `PHPCS23Utils` ruleset with one `PHPCS23Utils.Load.LoadUtils` sniff.
The only thing this standard does is trigger the PHPCSUtils autoload file in PHPCS 2.x.

This standard will not include any utilities or real sniffs. It is just in place to enable support for PHPCS 2.x in an as-simple-as-possible manner.
This:
* Adds a custom PHPCS ruleset which uses the `PHPCSDev` ruleset to check the code style of code in this repo, with a few, very select, exclusions.
* Adds convenience scripts to the `composer.json` file to check the code of the repo.
* And allows for individual developers to overload the `phpcs.xml.dist` file by ignoring the typical overload files.

**Important notes**:
1. The `compose require` is done directly in the Composer script rather than in the `require-dev` section as the PHPCS requirements for the `PHPCSDevTools` package can conflict with the PHPCS requirements of this package.

The CS check for this package should always be run on a recent PHPCS version to get the benefit of new sniffs, while the Utils themselves are - and should be - compatible with a wider range of PHPCS versions.

2. Using the above "trick" runs into issues when trying to remove the package on Travis due to some phantom _uncommitted changes in the `vendor/phpcstandards/phpcsdevtools` directory_. So, a separate script is used for Travis which doesn't `composer remove` of `PHPCSDevTools`.

3. For the time being - until v 1.0.0 has been tagged for the `PHPCSDevTools` package -, the `require` will use the `dev-develop` branch of `PHPCSDevTools`.

Also, the `composer validate` check doesn't need to be run on every build. Running it on just one build is sufficient, so moving it to the `sniff` stage.
@jrfnl jrfnl added this to the 1.0.0 milestone Dec 26, 2019
@jrfnl jrfnl merged commit 8a17759 into develop Dec 26, 2019
@jrfnl jrfnl deleted the feature/add-the-base-rulesets branch December 27, 2019 12:53
@jrfnl jrfnl modified the milestones: 1.0.0, 1.0.0-alpha1 May 1, 2020
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

Successfully merging this pull request may close these issues.

1 participant