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

Release WPCS 2.0.0-RC1
WordPress · Dec 30, 2018 · c0877a9 · c0877a9
2 parents f328bca + 9b17fe2
commit c0877a9
Show file tree

Hide file tree

Showing 321 changed files with 1,432 additions and 8,764 deletions.
diff --git a/.gitattributes b/.gitattributes
@@ -9,7 +9,6 @@
 /phpunit.xml.dist export-ignore
 /.github export-ignore
 /bin export-ignore
-/Test export-ignore
 /WordPress/Tests export-ignore
 
 #

diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md
@@ -37,111 +37,78 @@ When you introduce new `public` sniff properties, or your sniff extends a class
 > **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.
+> Support for the WPCS native whitelist comments has been deprecated in WPCS 2.0.0 and will be removed in WPCS 3.0.0.
 >
-> 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\Security;
-
-use WordPress\Sniff;
-
-class NonceVerificationSniff extends Sniff {
-
-	public function process_token( $stackPtr ) {
-
-		// Check something.
-
-		if ( $this->has_whitelist_comment( 'CSRF', $stackPtr ) ) {
-			return;
-		}
-
-		$this->phpcsFile->addError( ... );
-	}
-}
-```
-
-When you introduce a new whitelist comment, please don't forget to update the [whitelisting code wiki page](https://github.com/WordPress-Coding-Standards/WordPress-Coding-Standards/wiki/Whitelisting-code-which-flags-errors) with the relevant details once your PR has been merged into the `develop` branch.
+> With that in mind, (new) sniffs should not introduce new WPCS native whitelist comments.
 
 
 # Unit Testing
 
 ## Pre-requisites
 * WordPress-Coding-Standards
-* PHP_CodeSniffer 2.9.x or 3.x
+* PHP_CodeSniffer 3.3.1 or higher
 * 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.
+The WordPress Coding Standards use the `PHP_CodeSniffer` native unit test suite for unit testing the sniffs.
 
-Presuming you have installed PHP_CodeSniffer and the WordPress-Coding-Standards as [noted in the README](https://github.com/WordPress-Coding-Standards/WordPress-Coding-Standards#how-to-use-this), all you need now is `PHPUnit`.
+Presuming you have installed `PHP_CodeSniffer` and the WordPress-Coding-Standards as [noted in the README](https://github.com/WordPress-Coding-Standards/WordPress-Coding-Standards#how-to-use-this), all you need now is `PHPUnit`.
 
-N.B.: If you installed WPCS using Composer, make sure you used `--prefer-source` or run `composer install --prefer-source` now to make sure the unit tests are available.
+> N.B.: If you installed WPCS using Composer, make sure you used `--prefer-source` or run `composer install --prefer-source` now to make sure the unit tests are available.
+> Other than that, you're all set already as Composer will have installed PHPUnit for you.
 
 If you already have PHPUnit installed on your system: Congrats, you're all set.
 
-If not, you can navigate to the directory where the `PHP_CodeSniffer` repo is checked out and do `composer install` to install the `dev` dependencies.
-Alternatively, you can [install PHPUnit](https://phpunit.de/manual/5.7/en/installation.html) as a PHAR file.
+## Installing PHPUnit
+
+N.B.: _If you used Composer to install the WordPress Coding Standards, you can skip this step._
+
+You can either navigate to the directory where the `PHP_CodeSniffer` repo is checked out and do `composer install` to install the `dev` dependencies or you can [install PHPUnit](https://phpunit.readthedocs.io/en/7.4/installation.html) as a PHAR file.
+
+You may want to add the directory where PHPUnit is installed to a `PATH` environment variable for your operating system to make the command available everywhere on your system.
 
 ## Before running the unit tests
 
 N.B.: _If you used Composer to install the WordPress Coding Standards, you can skip this step._
 
 For the unit tests to work, you need to make sure PHPUnit can find your `PHP_CodeSniffer` install.
 
-The easiest way to do this is to add a `phpunit.xml` file to the root of your WPCS installation and set a `PHPCS_DIR` environment variable from within this file. Make sure to adjust the path to reflect your local setup.
+The easiest way to do this is to add a `phpunit.xml` file to the root of your WPCS installation and set a `PHPCS_DIR` environment variable from within this file.
+Copy the existing `phpunit.xml.dist` file and add the below `<env>` directive within the `<php>` section. Make sure to adjust the path to reflect your local setup.
 ```xml
-<phpunit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-	xsi:noNamespaceSchemaLocation="https://schema.phpunit.de/6.3/phpunit.xsd"
-	beStrictAboutTestsThatDoNotTestAnything="false"
-	backupGlobals="true">
 	<php>
 		<env name="PHPCS_DIR" value="/path/to/PHP_CodeSniffer/"/>
 	</php>
-</phpunit>
 ```
 
 ## Running the unit tests
 
-The WordPress Coding Standards are compatible with both PHPCS 2.x as well as 3.x. This has some implications for running the unit tests.
-
-* Make sure you have registered the directory in which you installed WPCS with PHPCS using;
+* If you didn't install WPCS using Composer, make sure you have registered the directory in which you installed WPCS with PHPCS using:
     ```sh
     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:
+* To run the unit tests:
     ```sh
-    phpunit --bootstrap="./Test/phpcs3-bootstrap.php" --filter WordPress /path/to/PHP_CodeSniffer/tests/AllTests.php
-    ```
-* To run the unit tests with PHPCS 2.x:
-    ```sh
-    phpunit --bootstrap="./Test/phpcs2-bootstrap.php" --filter WordPress ./Test/AllTests.php
+    phpunit --filter WordPress --bootstrap="/path/to/PHP_CodeSniffer/tests/bootstrap.php" /path/to/PHP_CodeSniffer/tests/AllTests.php
+
+    # Or if you've installed WPCS with Composer:
+    composer run-tests
     ```
 
 Expected output:
 ```
-PHPUnit 6.5.8 by Sebastian Bergmann and contributors.
+PHPUnit 7.5.0 by Sebastian Bergmann and contributors.
 
-Runtime:       PHP 7.2.7 with Xdebug 2.6.0
+Runtime:       PHP 7.2.13
 Configuration: /WordPressCS/phpunit.xml
 
-................................................................. 65 / 77 ( 84%)
-............                                                      77 / 77 (100%)
+........................................................          56 / 56 (100%)
 
-Tests generated 576 unique error codes; 51 were fixable (8.85%)
+152 sniff test files generated 487 unique error codes; 52 were fixable (10.68%)
 
-Time: 22.93 seconds, Memory: 40.00MB
+Time: 21.36 seconds, Memory: 22.00MB
 
-OK (77 tests, 0 assertions)
+OK (56 tests, 0 assertions)
 ```
 
 [![asciicast](https://asciinema.org/a/98078.png)](https://asciinema.org/a/98078)
@@ -154,7 +121,7 @@ Lets take a look at what's inside `POSIXFunctionsUnitTest.php`:
 
 ```php
 ...
-namespace WordPress\Tests\PHP;
+namespace WordPressCS\WordPress\Tests\PHP;
 
 use PHP_CodeSniffer\Tests\Standards\AbstractSniffUnitTest;
 

diff --git a/.github/ISSUE_TEMPLATE/dependency-change.md b/.github/ISSUE_TEMPLATE/dependency-change.md
@@ -4,7 +4,7 @@ about: A reminder to take action when a WPCS dependency changes
 
 ---
 
-<!-- PLEASE prefix the title the Issue with the dependency name and version when action should be taken e.g. PHPCS 3.3: ... -->
+<!-- PLEASE prefix the title the Issue with the dependency name and version when action should be taken e.g. PHPCS 3.5: ... -->
 
 ## Rationale
 

diff --git a/.github/issue_template.md b/.github/issue_template.md
diff --git a/.phpcs.xml.dist b/.phpcs.xml.dist
@@ -1,17 +1,14 @@
 <?xml version="1.0"?>
-<ruleset name="WordPress Coding Standards">
+<ruleset xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" name="WordPress Coding Standards" xsi:noNamespaceSchemaLocation="https://raw.githubusercontent.com/squizlabs/PHP_CodeSniffer/master/phpcs.xsd">
+
 	<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>
 
@@ -29,13 +26,14 @@
 	<rule ref="WordPress.Arrays.MultipleStatementAlignment">
 		<properties>
 			<property name="alignMultilineItems" value="!=100"/>
+			<property name="exact" value="false" phpcs-only="true"/>
 		</properties>
 	</rule>
 
 	<rule ref="PSR2.Methods.FunctionClosingBrace"/>
 
 	<!-- Check code for cross-version PHP compatibility. -->
-	<config name="testVersion" value="5.3-"/>
+	<config name="testVersion" value="5.4-"/>
 	<rule ref="PHPCompatibility">
 		<!-- Exclude PHP constants back-filled by PHPCS. -->
 		<exclude name="PHPCompatibility.Constants.NewConstants.t_finallyFound"/>
@@ -47,9 +45,12 @@
 		<exclude name="PHPCompatibility.Constants.NewConstants.t_coalesceFound"/>
 		<exclude name="PHPCompatibility.Constants.NewConstants.t_coalesce_equalFound"/>
 		<exclude name="PHPCompatibility.Constants.NewConstants.t_yield_fromFound"/>
+	</rule>
 
-		<!-- Unclear how, but appears to be back-filled anyhow, could be that PHP did so before the token was in use. -->
-		<exclude name="PHPCompatibility.Constants.NewConstants.t_traitFound"/>
+	<rule ref="WordPress.NamingConventions.PrefixAllGlobals.DeprecatedWhitelistCommentFound">
+		<!-- False positive for whitelist comment recognition, but no use fixing this now
+			 as the WPCS native whitelist comments are deprecated anyhow. -->
+		<exclude-pattern>/WordPress/AbstractClassRestrictionsSniff\.php$</exclude-pattern>
 	</rule>
 
 </ruleset>
diff --git a/.travis.yml b/.travis.yml
@@ -26,10 +26,8 @@ php:
 env:
   # `master` is now 3.x.
   - 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"
+  # Lowest supported release in the 3.x series with which WPCS is compatible.
+  - PHPCS_BRANCH="3.3.1"
 
 matrix:
   fast_finish: true
@@ -42,22 +40,9 @@ matrix:
           packages:
             - libxml2-utils
 
-    # 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
-      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
-      dist: precise
-
   allow_failures:
     # Allow failures for unstable builds.
     - php: nightly
-    - php: 7.3
-      env: PHPCS_BRANCH="3.1.0"
-    - php: 7.3
-      env: PHPCS_BRANCH="2.9.0"
 
 before_install:
     # Speed up build time by disabling Xdebug.
@@ -66,36 +51,21 @@ before_install:
     - phpenv config-rm xdebug.ini || echo 'No xdebug config.'
     - export XMLLINT_INDENT="	"
     - export PHPUNIT_DIR=/tmp/phpunit
-    - |
-      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
+    - composer require squizlabs/php_codesniffer:${PHPCS_BRANCH} --update-no-dev --no-suggest --no-scripts
     - |
       if [[ "$SNIFF" == "1" ]]; then
           composer install --dev --no-suggest
-          # The post-install-cmd script takes care of the installed_paths.
+          # The `dev` required DealerDirect Composer plugin 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.
-    - 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 . -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 $(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 $(pwd)/vendor/squizlabs/php_codesniffer/tests/AllTests.php; fi
+    - phpunit --filter WordPress --bootstrap="$(pwd)/vendor/squizlabs/php_codesniffer/tests/bootstrap.php" $(pwd)/vendor/squizlabs/php_codesniffer/tests/AllTests.php
     # 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).
@@ -108,22 +78,20 @@ script:
     - 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 $(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
-    - if [[ "$SNIFF" == "1" ]]; then xmllint --noout ./phpcs.xml.dist.sample; fi
+    - if [[ "$SNIFF" == "1" ]]; then xmllint --noout --schema ./vendor/squizlabs/php_codesniffer/phpcs.xsd ./*/ruleset.xml; fi
+    - if [[ "$SNIFF" == "1" ]]; then xmllint --noout --schema ./vendor/squizlabs/php_codesniffer/phpcs.xsd ./phpcs.xml.dist.sample; fi
     # Check the code-style consistency of the xml files.
     - if [[ "$SNIFF" == "1" ]]; then diff -B --tabsize=4 ./WordPress/ruleset.xml <(xmllint --format "./WordPress/ruleset.xml"); fi
     - if [[ "$SNIFF" == "1" ]]; then diff -B --tabsize=4 ./WordPress-Core/ruleset.xml <(xmllint --format "./WordPress-Core/ruleset.xml"); fi
     - if [[ "$SNIFF" == "1" ]]; then diff -B --tabsize=4 ./WordPress-Docs/ruleset.xml <(xmllint --format "./WordPress-Docs/ruleset.xml"); fi
     - 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