Merge pull request #1392 from WordPress-Coding-Standards/develop

Release version 1.0.0

.gitattributes

@@ -5,6 +5,7 @@
 # https://blog.madewithlove.be/post/gitattributes/
 #
 /.travis.yml export-ignore
+/.phpcs.xml.dist export-ignore
 /phpunit.xml.dist export-ignore
 /.github export-ignore
 /bin export-ignore

.github/CONTRIBUTING.md

@@ -15,7 +15,7 @@ Since WPCS employs many sniffs that are part of PHPCS, sometimes an issue will b
 
 ## Branches
 
-Ongoing development will be done in the `develop` with merges done into `master` once considered stable.
+Ongoing development will be done in the `develop` branch with merges done into `master` once considered stable.
 
 To contribute an improvement to this project, fork the repo and open a pull request to the `develop` branch. Alternatively, if you have push access to this repo, create a feature branch prefixed by `feature/` and then open an intra-repo PR from that branch to `develop`.
 
@@ -32,14 +32,24 @@ When you introduce new `public` sniff properties, or your sniff extends a class
 
 ## Whitelist comments
 
+> **Important**:
+> PHPCS 3.2.0 introduced new selective ignore annotations, which can be considered an improved version of the whitelist mechanism which WPCS contains.
+>
+> There is a [tentative intention to drop support for the WPCS native whitelist comments](https://github.com/WordPress-Coding-Standards/WordPress-Coding-Standards/issues/1048#issuecomment-340698249) in WPCS 2.0.0.
+> 
+> Considering that, the introduction of new whitelist comments is discouraged.
+>
+> The below information remains as guidance for exceptional cases and to aid in understanding the previous implementation.
+
 Sometimes, a sniff will flag code which upon further inspection by a human turns out to be OK.
+
 If the sniff you are writing is susceptible to this, please consider adding the ability to [whitelist lines of code](https://github.com/WordPress-Coding-Standards/WordPress-Coding-Standards/wiki/Whitelisting-code-which-flags-errors).
 
 To this end, the `WordPress\Sniff::has_whitelist_comment()` method was introduced.
 
 Example usage:
 ```php
-namespace WordPress\Sniffs\CSRF;
+namespace WordPress\Sniffs\Security;
 
 use WordPress\Sniff;
 
@@ -66,7 +76,7 @@ When you introduce a new whitelist comment, please don't forget to update the [w
 ## Pre-requisites
 * WordPress-Coding-Standards
 * PHP_CodeSniffer 2.9.x or 3.x
-* PHPUnit 4.x, 5.x or 6.x
+* PHPUnit 4.x, 5.x, 6.x or 7.x
 
 The WordPress Coding Standards use the PHP_CodeSniffer native unit test suite for unit testing the sniffs.
 
@@ -103,7 +113,7 @@ The WordPress Coding Standards are compatible with both PHPCS 2.x as well as 3.x
 
 * Make sure you have registered the directory in which you installed WPCS with PHPCS using;
     ```sh
-    phpcs --config-set installed_path path/to/WPCS
+    phpcs --config-set installed_paths path/to/WPCS
     ```
 * Navigate to the directory in which you installed WPCS.
 * To run the unit tests with PHPCS 3.x:
@@ -117,18 +127,19 @@ The WordPress Coding Standards are compatible with both PHPCS 2.x as well as 3.x
 
 Expected output:
 ```
-PHPUnit 4.8.19 by Sebastian Bergmann and contributors.
+PHPUnit 6.5.8 by Sebastian Bergmann and contributors.
 
-Runtime:        PHP 7.1.3 with Xdebug 2.5.1
-Configuration:  /WordPressCS/phpunit.xml
+Runtime:       PHP 7.2.7 with Xdebug 2.6.0
+Configuration: /WordPressCS/phpunit.xml
 
-..........................................................
+................................................................. 65 / 77 ( 84%)
+............                                                      77 / 77 (100%)
 
-Tests generated 556 unique error codes; 48 were fixable (8.63%)
+Tests generated 576 unique error codes; 51 were fixable (8.85%)
 
-Time: 24.08 seconds, Memory: 41.75Mb
+Time: 22.93 seconds, Memory: 40.00MB
 
-OK (58 tests, 0 assertions)
+OK (77 tests, 0 assertions)
 ```
 
 [![asciicast](https://asciinema.org/a/98078.png)](https://asciinema.org/a/98078)
@@ -207,4 +218,4 @@ The `--sniffs=...` directive limits the output to the sniff you are testing.
 
 ## Code Standards for this project
 
-The sniffs and test files - not test _case_ files! - for WPCS should be written such that they pass the `WordPress-Extra` and the `WordPress-Docs` code standards using the custom ruleset as found in `/bin/phpcs.xml`.
+The sniffs and test files - not test _case_ files! - for WPCS should be written such that they pass the `WordPress-Extra` and the `WordPress-Docs` code standards using the custom ruleset as found in `/.phpcs.xml.dist`.

.gitignore

@@ -4,3 +4,5 @@
 vendor
 composer.lock
 phpunit.xml
+phpcs.xml
+.phpcs.xml

.phpcs.xml.dist

@@ -0,0 +1,55 @@
+<?xml version="1.0"?>
+<ruleset name="WordPress Coding Standards">
+	<description>The Coding standard for the WordPress Coding Standards itself.</description>
+
+	<file>.</file>
+
+	<arg value="sp"/>
+	<arg name="extensions" value="php"/>
+
+	<!-- Exclude the code in the PHPCS 2.x test files copied in from PHPCS. -->
+	<exclude-pattern>/Test/AllTests.php</exclude-pattern>
+	<exclude-pattern>/Test/Standards/*.php</exclude-pattern>
+	<exclude-pattern>/bin/class-ruleset-test.php</exclude-pattern>
+
+	<!-- Exclude Composer vendor directory. -->
+	<exclude-pattern>*/vendor/*</exclude-pattern>
+
+	<rule ref="WordPress-Extra">
+		<exclude name="WordPress.Files.FileName"/>
+		<exclude name="WordPress.NamingConventions.ValidVariableName"/>
+		<exclude name="WordPress.CodeAnalysis.AssignmentInCondition.FoundInWhileCondition"/>
+	</rule>
+
+	<rule ref="WordPress-Docs"/>
+
+	<!-- Enforce PSR1 compatible namespaces. -->
+	<rule ref="PSR1.Classes.ClassDeclaration"/>
+
+	<rule ref="WordPress.Arrays.MultipleStatementAlignment">
+		<properties>
+			<property name="alignMultilineItems" value="!=100"/>
+		</properties>
+	</rule>
+
+	<rule ref="PSR2.Methods.FunctionClosingBrace"/>
+
+	<!-- Check code for cross-version PHP compatibility. -->
+	<config name="testVersion" value="5.3-"/>
+	<rule ref="PHPCompatibility">
+		<!-- Exclude PHP constants back-filled by PHPCS. -->
+		<exclude name="PHPCompatibility.PHP.NewConstants.t_finallyFound"/>
+		<exclude name="PHPCompatibility.PHP.NewConstants.t_yieldFound"/>
+		<exclude name="PHPCompatibility.PHP.NewConstants.t_ellipsisFound"/>
+		<exclude name="PHPCompatibility.PHP.NewConstants.t_powFound"/>
+		<exclude name="PHPCompatibility.PHP.NewConstants.t_pow_equalFound"/>
+		<exclude name="PHPCompatibility.PHP.NewConstants.t_spaceshipFound"/>
+		<exclude name="PHPCompatibility.PHP.NewConstants.t_coalesceFound"/>
+		<exclude name="PHPCompatibility.PHP.NewConstants.t_coalesce_equalFound"/>
+		<exclude name="PHPCompatibility.PHP.NewConstants.t_yield_fromFound"/>
+
+		<!-- Unclear how, but appears to be back-filled anyhow, could be that PHP did so before the token was in use. -->
+		<exclude name="PHPCompatibility.PHP.NewConstants.t_traitFound"/>
+	</rule>
+
+</ruleset>

.travis.yml

@@ -19,74 +19,91 @@ php:
 
 env:
   # `master` is now 3.x.
-  - PHPCS_BRANCH=master LINT=1
+  - PHPCS_BRANCH="dev-master" LINT=1
+  # Lowest supported release in the 3.x series with which WPCS is compatible (and which can run the unit tests).
+  - PHPCS_BRANCH="3.1.0"
   # Lowest tagged release in the 2.x series with which WPCS is compatible.
-  - PHPCS_BRANCH=2.9.0
+  - PHPCS_BRANCH="2.9.0"
 
 matrix:
   fast_finish: true
   include:
-    # Run PHPCS against WPCS. I just picked to run it against 7.0.
-    - php: 7.0
-      env: PHPCS_BRANCH=master SNIFF=1
+    # Run PHPCS against WPCS. I just picked to run it against 7.2.
+    - php: 7.2
+      env: PHPCS_BRANCH="dev-master" SNIFF=1
       addons:
         apt:
           packages:
             - libxml2-utils
 
-    # Run against HHVM.
-    - php: hhvm
-      sudo: required
-      dist: trusty
-      group: edge
-      env: PHPCS_BRANCH=master LINT=1
-
     # Test PHP 5.3 only against PHPCS 2.x as PHPCS 3.x has a minimum requirement of PHP 5.4.
     - php: 5.3
-      env: PHPCS_BRANCH=2.9 LINT=1
+      env: PHPCS_BRANCH="2.9.*" LINT=1
       dist: precise
     # Test PHP 5.3 with short_open_tags set to On (is Off by default)
     - php: 5.3
-      env: PHPCS_BRANCH=2.9.0 SHORT_OPEN_TAGS=true
+      env: PHPCS_BRANCH="2.9.0" SHORT_OPEN_TAGS=true
       dist: precise
 
   allow_failures:
     # Allow failures for unstable builds.
     - php: nightly
-    - php: hhvm
 
 before_install:
+    # Speed up build time by disabling Xdebug.
+    # https://johnblackbourn.com/reducing-travis-ci-build-times-for-wordpress-projects/
+    # https://twitter.com/kelunik/status/954242454676475904
+    - phpenv config-rm xdebug.ini || echo 'No xdebug config.'
     - export XMLLINT_INDENT="	"
-    - export PHPCS_DIR=/tmp/phpcs
     - export PHPUNIT_DIR=/tmp/phpunit
-    - export PHPCS_BIN=$(if [[ $PHPCS_BRANCH == master ]]; then echo $PHPCS_DIR/bin/phpcs; else echo $PHPCS_DIR/scripts/phpcs; fi)
-    - mkdir -p $PHPCS_DIR && git clone --depth 1 https://github.com/squizlabs/PHP_CodeSniffer.git -b $PHPCS_BRANCH $PHPCS_DIR
-    - $PHPCS_BIN --config-set installed_paths $(pwd)
-    # Download PHPUnit 5.x for builds on PHP 7, nightly and HHVM as the PHPCS
+    - |
+      if [[ ${PHPCS_BRANCH:0:2} == "2." ]]; then
+          # --prefer-source is needed to ensure that the PHPCS unit test suite is available in PHPCS 2.9.
+          composer require squizlabs/php_codesniffer:${PHPCS_BRANCH} --prefer-source --update-no-dev --no-suggest --no-scripts
+      else
+          composer require squizlabs/php_codesniffer:${PHPCS_BRANCH} --update-no-dev --no-suggest --no-scripts
+      fi
+    - |
+      if [[ "$SNIFF" == "1" ]]; then
+          composer install --dev --no-suggest
+          # The post-install-cmd script takes care of the installed_paths.
+      else
+          # The above require already does the install.
+          $(pwd)/vendor/bin/phpcs --config-set installed_paths $(pwd)
+      fi
+    # Download PHPUnit 5.x for builds on PHP 7 and nightly as the PHPCS
     # test suite is currently not compatible with PHPUnit 6.x.
-    # Fixed at a very specific PHPUnit version which is also compatible with HHVM.
+    # Fixed at a very specific PHPUnit version.
     - if [[ ${TRAVIS_PHP_VERSION:0:2} != "5." ]]; then wget -P $PHPUNIT_DIR https://phar.phpunit.de/phpunit-5.7.17.phar && chmod +x $PHPUNIT_DIR/phpunit-5.7.17.phar; fi
     # Selectively adjust the ini values for the build image to test ini value dependent sniff features.
     - if [[ "$SHORT_OPEN_TAGS" == "true" ]]; then echo "short_open_tag = On" >> ~/.phpenv/versions/$(phpenv version-name)/etc/php.ini; fi
 
 script:
     # Lint the PHP files against parse errors.
-    - if [[ "$LINT" == "1" ]]; then if find . -name "*.php" -exec php -l {} \; | grep "^[Parse error|Fatal error]"; then exit 1; fi; fi
+    - if [[ "$LINT" == "1" ]]; then if find . -path ./vendor -prune -o -path ./bin -prune -o -name "*.php" -exec php -l {} \; | grep "^[Parse error|Fatal error]"; then exit 1; fi; fi
     # Run the unit tests.
     - if [[ ${TRAVIS_PHP_VERSION:0:2} == "5." && ${PHPCS_BRANCH:0:2} == "2." ]]; then phpunit --filter WordPress $(pwd)/Test/AllTests.php; fi
-    - if [[ ${TRAVIS_PHP_VERSION:0:2} == "5." && ${PHPCS_BRANCH:0:2} != "2." ]]; then phpunit --filter WordPress $PHPCS_DIR/tests/AllTests.php; fi
+    - if [[ ${TRAVIS_PHP_VERSION:0:2} == "5." && ${PHPCS_BRANCH:0:2} != "2." ]]; then phpunit --filter WordPress $(pwd)/vendor/squizlabs/php_codesniffer/tests/AllTests.php; fi
     - if [[ ${TRAVIS_PHP_VERSION:0:2} != "5." && ${PHPCS_BRANCH:0:2} == "2." ]]; then php $PHPUNIT_DIR/phpunit-5.7.17.phar --filter WordPress $(pwd)/Test/AllTests.php; fi
-    - if [[ ${TRAVIS_PHP_VERSION:0:2} != "5." && ${PHPCS_BRANCH:0:2} != "2." ]]; then php $PHPUNIT_DIR/phpunit-5.7.17.phar  --filter WordPress $PHPCS_DIR/tests/AllTests.php; fi
+    - if [[ ${TRAVIS_PHP_VERSION:0:2} != "5." && ${PHPCS_BRANCH:0:2} != "2." ]]; then php $PHPUNIT_DIR/phpunit-5.7.17.phar  --filter WordPress $(pwd)/vendor/squizlabs/php_codesniffer/tests/AllTests.php; fi
     # Test for fixer conflicts by running the auto-fixers of the complete WPCS over the test case files.
     # This is not an exhaustive test, but should give an early indication for typical fixer conflicts.
     # For the first run, the exit code will be 1 (= all fixable errors fixed).
     # `travis_retry` should then kick in to run the fixer again which should now return 0 (= no fixable errors found).
     # All error codes for the PHPCBF: https://github.com/squizlabs/PHP_CodeSniffer/issues/1270#issuecomment-272768413
-    - if [[ "$SNIFF" == "1" ]]; then travis_retry $PHPCS_DIR/bin/phpcbf -p ./WordPress/Tests/ --standard=WordPress --extensions=inc --exclude=Generic.PHP.Syntax --report=summary; fi
+    - if [[ "$SNIFF" == "1" ]]; then travis_retry $(pwd)/vendor/bin/phpcbf -p ./WordPress/Tests/ --standard=WordPress --extensions=inc --exclude=Generic.PHP.Syntax --report=summary; fi
+    # Make sure the rulesets don't thrown unexpected errors or warnings.
+    # This check needs to be run against a high PHP version to prevent triggering the syntax error check.
+    # It also needs to be run against all PHPCS versions WPCS is tested against.
+    - if [[ $TRAVIS_PHP_VERSION == "7.1" ]]; then $(pwd)/vendor/bin/phpcs -s ./bin/class-ruleset-test.php --standard=WordPress-Core; fi
+    - if [[ $TRAVIS_PHP_VERSION == "7.1" ]]; then $(pwd)/vendor/bin/phpcs -s ./bin/class-ruleset-test.php --standard=WordPress-Docs; fi
+    - if [[ $TRAVIS_PHP_VERSION == "7.1" ]]; then $(pwd)/vendor/bin/phpcs -s ./bin/class-ruleset-test.php --standard=WordPress-Extra; fi
+    - if [[ $TRAVIS_PHP_VERSION == "7.1" ]]; then $(pwd)/vendor/bin/phpcs -s ./bin/class-ruleset-test.php --standard=WordPress-VIP; fi
+    - if [[ $TRAVIS_PHP_VERSION == "7.1" ]]; then $(pwd)/vendor/bin/phpcs -s ./bin/class-ruleset-test.php --standard=WordPress; fi
     # WordPress Coding Standards.
     # @link https://github.com/WordPress-Coding-Standards/WordPress-Coding-Standards
     # @link http://pear.php.net/package/PHP_CodeSniffer/
-    - if [[ "$SNIFF" == "1" ]]; then $PHPCS_BIN . --standard=./bin/phpcs.xml --runtime-set ignore_warnings_on_exit 1; fi
+    - if [[ "$SNIFF" == "1" ]]; then $(pwd)/vendor/bin/phpcs --runtime-set ignore_warnings_on_exit 1; fi
     # Validate the xml files.
     # @link http://xmlsoft.org/xmllint.html
     - if [[ "$SNIFF" == "1" ]]; then xmllint --noout ./*/ruleset.xml; fi
@@ -98,3 +115,6 @@ script:
     - if [[ "$SNIFF" == "1" ]]; then diff -B --tabsize=4 ./WordPress-Extra/ruleset.xml <(xmllint --format "./WordPress-Extra/ruleset.xml"); fi
     - if [[ "$SNIFF" == "1" ]]; then diff -B --tabsize=4 ./WordPress-VIP/ruleset.xml <(xmllint --format "./WordPress-VIP/ruleset.xml"); fi
     - if [[ "$SNIFF" == "1" ]]; then diff -B --tabsize=4 ./phpcs.xml.dist.sample <(xmllint --format "./phpcs.xml.dist.sample"); fi
+    # Validate the composer.json file.
+    # @link https://getcomposer.org/doc/03-cli.md#validate
+    - if [[ "$LINT" == "1" ]]; then composer validate --no-check-all --strict; fi