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

Release version 0.14.0

.github/CONTRIBUTING.md

@@ -65,12 +65,12 @@ 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 or 5.x
+* PHP_CodeSniffer 2.9.x or 3.x
+* PHPUnit 4.x, 5.x or 6.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.
 
@@ -88,7 +88,8 @@ For the unit tests to work, you need to make sure PHPUnit can find your `PHP_Cod
 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.
 ```xml
 <phpunit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-	xsi:noNamespaceSchemaLocation="http://schema.phpunit.de/4.1/phpunit.xsd"
+	xsi:noNamespaceSchemaLocation="https://schema.phpunit.de/6.3/phpunit.xsd"
+	beStrictAboutTestsThatDoNotTestAnything="false"
 	backupGlobals="true">
 	<php>
 		<env name="PHPCS_DIR" value="/path/to/PHP_CodeSniffer/"/>
@@ -121,13 +122,13 @@ PHPUnit 4.8.19 by Sebastian Bergmann and contributors.
 Runtime:        PHP 7.1.3 with Xdebug 2.5.1
 Configuration:  /WordPressCS/phpunit.xml
 
-......................................................
+..........................................................
 
-Tests generated 558 unique error codes; 48 were fixable (8.6%)
+Tests generated 556 unique error codes; 48 were fixable (8.63%)
 
-Time: 12.25 seconds, Memory: 24.00Mb
+Time: 24.08 seconds, Memory: 41.75Mb
 
-OK (54 tests, 0 assertions)
+OK (58 tests, 0 assertions)
 ```
 
 [![asciicast](https://asciinema.org/a/98078.png)](https://asciinema.org/a/98078)

.travis.yml

@@ -14,6 +14,7 @@ php:
     - 5.6
     - 7.0
     - 7.1
+    - 7.2
     - nightly
 
 env:
@@ -33,7 +34,7 @@ matrix:
           packages:
             - libxml2-utils
 
-    # Run against HHVM and PHP nightly.
+    # Run against HHVM.
     - php: hhvm
       sudo: required
       dist: trusty
@@ -76,15 +77,15 @@ script:
     - 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 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
+    # 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
     # WordPress Coding Standards.
     # @link https://github.com/WordPress-Coding-Standards/WordPress-Coding-Standards
     # @link http://pear.php.net/package/PHP_CodeSniffer/
-    # -p flag: Show progress of the run.
-    # -s flag: Show sniff codes in all reports.
-    # -v flag: Print verbose output.
-    # -n flag: Do not print warnings. (shortcut for --warning-severity=0)
-    # --standard: Use WordPress as the standard.
-    # --extensions: Only sniff PHP files.
     - if [[ "$SNIFF" == "1" ]]; then $PHPCS_BIN . --standard=./bin/phpcs.xml --runtime-set ignore_warnings_on_exit 1; fi
     # Validate the xml files.
     # @link http://xmlsoft.org/xmllint.html

README.md

@@ -42,7 +42,7 @@ This project is a collection of [PHP_CodeSniffer](https://github.com/squizlabs/P
 
 ### Requirements
 
-The WordPress Coding Standards require PHP 5.3 or higher and [PHP CodeSniffer](https://github.com/squizlabs/PHP_CodeSniffer) version **2.9.0** or higher.
+The WordPress Coding Standards require PHP 5.3 or higher and [PHP_CodeSniffer](https://github.com/squizlabs/PHP_CodeSniffer) version **2.9.0** or higher.
 As of version 0.13.0, the WordPress Coding Standards are compatible with PHPCS 3.0.2+. In that case, the minimum PHP requirement is PHP 5.4.
 
 ### Composer
@@ -66,15 +66,15 @@ When installing the WordPress Coding Standards as a dependency in a larger proje
 
 There are two actively maintained Composer plugins which can handle the registration of standards with PHP_CodeSniffer for you:
 * [composer-phpcodesniffer-standards-plugin](https://github.com/higidi/composer-phpcodesniffer-standards-plugin)
-* [phpcodesniffer-composer-installer](https://github.com/DealerDirect/phpcodesniffer-composer-installer):"^0.4.1"
+* [phpcodesniffer-composer-installer](https://github.com/DealerDirect/phpcodesniffer-composer-installer):"^0.4.3"
 
 It is strongly suggested to `require` one of these plugins in your project to handle the registration of external standards with PHPCS for you.
 
 ### Standalone
 
 1. Install PHP_CodeSniffer by following its [installation instructions](https://github.com/squizlabs/PHP_CodeSniffer#installation) (via Composer, Phar file, PEAR, or Git checkout).
 
-   Do ensure that PHP_CodeSniffer's version matches our requirements(#requirements), if, for example, you're using VVV(https://github.com/Varying-Vagrant-Vagrants/VVV).
+   Do ensure that PHP_CodeSniffer's version matches our [requirements](#requirements), if, for example, you're using [VVV](https://github.com/Varying-Vagrant-Vagrants/VVV).
 
 2. Clone the WordPress standards repository:
 
@@ -124,7 +124,7 @@ You can use the following as standard names when invoking `phpcs` to select snif
 
 ### Using a custom ruleset
 
-If you need to further customize the selection of sniffs for your project - you can create a custom ruleset file. When you name this file either `phpcs.xml` or `phpcs.xml.dist`, PHP_CodeSniffer will automatically locate it as long as it is placed in the directory from which you run the CodeSniffer or in a directory above it. If you follow these naming conventions you don't have to supply a `--standard` arg. For more info, read about [using a default configuration file](https://github.com/squizlabs/PHP_CodeSniffer/wiki/Advanced-Usage#using-a-default-configuration-file). See also provided [`phpcs.xml.dist.sample`](phpcs.xml.dist.sample) file and [fully annotated example](https://github.com/squizlabs/PHP_CodeSniffer/wiki/Annotated-ruleset.xml) in the PHP CodeSniffer documentation.
+If you need to further customize the selection of sniffs for your project - you can create a custom ruleset file. When you name this file either `phpcs.xml` or `phpcs.xml.dist`, PHP_CodeSniffer will automatically locate it as long as it is placed in the directory from which you run the CodeSniffer or in a directory above it. If you follow these naming conventions you don't have to supply a `--standard` arg. For more info, read about [using a default configuration file](https://github.com/squizlabs/PHP_CodeSniffer/wiki/Advanced-Usage#using-a-default-configuration-file). See also provided [`phpcs.xml.dist.sample`](phpcs.xml.dist.sample) file and [fully annotated example](https://github.com/squizlabs/PHP_CodeSniffer/wiki/Annotated-ruleset.xml) in the PHP_CodeSniffer documentation.
 
 ### Customizing sniff behaviour
 
@@ -212,12 +212,15 @@ sublime-phpcs is insanely powerful, but if you'd prefer automatic linting, [Subl
 - Install PHP Sniffer and WordPress Coding Standards per above.
 - Install [linter-phpcs](https://atom.io/packages/linter-phpcs) via Atom's package manager.
 - Run `which phpcs` to get your `phpcs` executable path.
-- Enter your `phpcs` executable path and one of the coding standards specified above (e.g. `WordPress`, `WordPress-VIP`, etc.).
+- Open the linter-phpcs package settings; enter your `phpcs` executable path and one of the coding standards specified above (e.g. `WordPress`, `WordPress-VIP`, etc.).
+- Below these settings find the Tab Width setting and change it to `4`.
 
 ![Atom Linter WordPress Coding Standards configuration](https://cloud.githubusercontent.com/assets/224636/12740504/ce4e97b8-c941-11e5-8d83-c77a2470d58e.png)
 
 ![Atom Linter in action using WordPress Coding Standards](https://cloud.githubusercontent.com/assets/224636/12740542/131c5894-c942-11e5-9e31-5e020c993224.png)
 
+- Note that certain items within PHPCS config file can cause linting to fail, see [linter-phpcs #95](https://github.com/AtomLinter/linter-phpcs/issues/95#issuecomment-316133107) for more details.
+
 ### Visual Studio
 
 Please see "[Setting up PHP CodeSniffer in Visual Studio Code](https://tommcfarlin.com/php-codesniffer-in-visual-studio-code/)", a tutorial by Tom McFarlin.
@@ -246,7 +249,7 @@ matrix:
 before_install:
   - if [[ "$SNIFF" == "1" ]]; then export PHPCS_DIR=/tmp/phpcs; fi
   - if [[ "$SNIFF" == "1" ]]; then export SNIFFS_DIR=/tmp/sniffs; fi
-  # Install PHP CodeSniffer.
+  # Install PHP_CodeSniffer.
   - if [[ "$SNIFF" == "1" ]]; then git clone -b master --depth 1 https://github.com/squizlabs/PHP_CodeSniffer.git $PHPCS_DIR; fi
   # Install WordPress Coding Standards.
   - if [[ "$SNIFF" == "1" ]]; then git clone -b master --depth 1 https://github.com/WordPress-Coding-Standards/WordPress-Coding-Standards.git $SNIFFS_DIR; fi

Test/phpcs2-bootstrap.php

@@ -20,7 +20,7 @@
 $phpcsDir = getenv( 'PHPCS_DIR' );
 
 if ( false === $phpcsDir && is_dir( dirname( __DIR__ ) . $ds . 'vendor' . $ds . 'squizlabs' . $ds . 'php_codesniffer' ) ) {
-	$phpcsDir  = dirname( __DIR__ ) . $ds . 'vendor' . $ds . 'squizlabs' . $ds . 'php_codesniffer';
+	$phpcsDir = dirname( __DIR__ ) . $ds . 'vendor' . $ds . 'squizlabs' . $ds . 'php_codesniffer';
 } elseif ( false !== $phpcsDir ) {
 	$phpcsDir = realpath( $phpcsDir );
 }
@@ -44,9 +44,9 @@
 }
 
 // Load the PHPCS test classes and the WPCS versions where necessary.
-include_once PHPCS_DIR . $ds . 'tests' . $ds . 'AllTests.php';
-include_once __DIR__ . $ds . 'Standards' . $ds . 'AllSniffs.php';
-include_once __DIR__ . $ds . 'Standards' . $ds . 'AbstractSniffUnitTest.php';
+require_once PHPCS_DIR . $ds . 'tests' . $ds . 'AllTests.php';
+require_once __DIR__ . $ds . 'Standards' . $ds . 'AllSniffs.php';
+require_once __DIR__ . $ds . 'Standards' . $ds . 'AbstractSniffUnitTest.php';
 
 class_alias( 'WordPressCS\Test\AbstractSniffUnitTest', 'PHP_CodeSniffer\Tests\Standards\AbstractSniffUnitTest' );
 

Test/phpcs3-bootstrap.php

@@ -26,14 +26,22 @@
 
 // This may be a Composer install.
 if ( false === $phpcsDir && is_dir( dirname( __DIR__ ) . $ds . 'vendor' . $ds . 'squizlabs' . $ds . 'php_codesniffer' ) ) {
-	$phpcsDir  = dirname( __DIR__ ) . $ds . 'vendor' . $ds . 'squizlabs' . $ds . 'php_codesniffer';
+	$phpcsDir = dirname( __DIR__ ) . $ds . 'vendor' . $ds . 'squizlabs' . $ds . 'php_codesniffer';
 } elseif ( false !== $phpcsDir ) {
 	$phpcsDir = realpath( $phpcsDir );
 }
 
 // Try and load the PHPCS autoloader.
 if ( false !== $phpcsDir && file_exists( $phpcsDir . $ds . 'autoload.php' ) ) {
 	require_once $phpcsDir . $ds . 'autoload.php';
+
+	/*
+	 * As of PHPCS 3.1, PHPCS support PHPUnit 6.x, but needs a bootstrap, so
+	 * load it if it's available.
+	 */
+	if ( file_exists( $phpcsDir . $ds . 'tests' . $ds . 'bootstrap.php' ) ) {
+		require_once $phpcsDir . $ds . 'tests' . $ds . 'bootstrap.php';
+	}
 } else {
 	echo 'Uh oh... can\'t find PHPCS. Are you sure you are using PHPCS 3.x ?
 
@@ -49,5 +57,5 @@
 }
 
 // Load our class aliases.
-include_once dirname( __DIR__ ) . $ds . 'WordPress' . $ds . 'PHPCSAliases.php';
+require_once dirname( __DIR__ ) . $ds . 'WordPress' . $ds . 'PHPCSAliases.php';
 unset( $ds, $phpcsDir );

WordPress-Core/ruleset.xml

@@ -46,6 +46,7 @@
 
 	<!-- Covers rule: Use real tabs and not spaces. -->
 	<rule ref="Generic.WhiteSpace.DisallowSpaceIndent"/>
+	<rule ref="WordPress.WhiteSpace.PrecisionAlignment"/>
 
 	<!-- Generic array layout check. -->
 	<!-- Covers rule: For associative arrays, values should start on a new line.
@@ -67,6 +68,21 @@
 	<!-- Covers rule: ... while spaces can be used mid-line for alignment. -->
 	<rule ref="WordPress.WhiteSpace.DisallowInlineTabs"/>
 
+	<!-- Implied through the examples: align the assignment operator in a block of assignments. -->
+	<rule ref="Generic.Formatting.MultipleStatementAlignment">
+		<properties>
+			<property name="maxPadding" value="40"/>
+		</properties>
+	</rule>
+
+	<!-- Implied through the examples: align the double arrows. -->
+	<rule ref="WordPress.Arrays.MultipleStatementAlignment">
+		<properties>
+			<property name="maxColumn" value="60"/>
+		</properties>
+	</rule>
+
+
 	<!--
 	#############################################################################
 	Handbook: PHP - Brace Style.
@@ -197,6 +213,8 @@
 	<!-- Related to issue #970 / https://github.com/squizlabs/PHP_CodeSniffer/issues/1512 -->
 	<rule ref="WordPress.Functions.FunctionCallSignatureNoParams"/>
 
+	<rule ref="Generic.Functions.FunctionCallArgumentSpacing"/>
+
 	<!-- Rule: Perform logical comparisons, like so: if ( ! $foo ) { -->
 
 	<!-- Covers rule: When type casting, do it like so: $foo = (boolean) $bar; -->
@@ -207,6 +225,21 @@
 	<!-- Covers rule: ... array items, only include a space around the index if it is a variable. -->
 	<rule ref="WordPress.Arrays.ArrayKeySpacingRestrictions"/>
 
+	<!-- Rule: In a switch block, there must be no space before the colon for a case statement. -->
+	<!-- Covered by the PSR2.ControlStructures.SwitchDeclaration sniff. -->
+
+	<!-- Rule: Similarly, there should be no space before the colon on return type declarations. -->
+
+	<!-- Covers rule: Unless otherwise specified, parentheses should have spaces inside of them. -->
+	<!-- Duplicate of upstream. Should defer to upstream version once minimum PHPCS requirement has gone up.
+		 https://github.com/squizlabs/PHP_CodeSniffer/pull/1701 -->
+	<rule ref="WordPress.WhiteSpace.ArbitraryParenthesesSpacing">
+		<properties>
+			<property name="spacingInside" value="1"/>
+			<property name="ignoreNewlines" value="true"/>
+		</properties>
+	</rule>
+
 
 	<!--
 	#############################################################################
@@ -221,8 +254,8 @@
 		 SQL slash escaping when passed.
 		 https://github.com/WordPress-Coding-Standards/WordPress-Coding-Standards/issues/640 -->
 
-	<!-- Rule: in $wpdb->prepare - only %s and %d are used as placeholders. Note that they are not "quoted"!
-		 https://github.com/WordPress-Coding-Standards/WordPress-Coding-Standards/issues/641 -->
+	<!-- Rule: in $wpdb->prepare - only %s and %d are used as placeholders. Note that they are not "quoted"! -->
+	<rule ref="WordPress.DB.PreparedSQLPlaceholders"/>
 
 	<!-- Covers rule: Escaping should be done as close to the time of the query as possible,
 		 preferably by using $wpdb->prepare() -->
@@ -331,6 +364,26 @@
 	     to the next block, this must be explicitly commented. -->
 	<!-- Covered by the PSR2.ControlStructures.SwitchDeclaration sniff. -->
 
+	<!-- Rule: The goto statement must never be used. -->
+	<!-- Duplicate of upstream. Should defer to upstream version once minimum PHPCS requirement has gone up.
+		 https://github.com/squizlabs/PHP_CodeSniffer/pull/1664 -->
+	<rule ref="WordPress.PHP.DiscourageGoto"/>
+	<rule ref="WordPress.PHP.DiscourageGoto.Found">
+		<type>error</type>
+		<message>The "goto" language construct should not be used.</message>
+	</rule>
+
+	<!-- Rule: The eval() construct is very dangerous, and is impossible to secure. ... these must not be used. -->
+	<rule ref="Squiz.PHP.Eval"/>
+	<rule ref="Squiz.PHP.Eval.Discouraged">
+		<type>error</type>
+		<message>eval() is a security risk so not allowed.</message>
+	</rule>
+
+	<!-- Rule: create_function() function, which internally performs an eval(),
+	     is deprecated in PHP 7.2. Both of these must not be used. -->
+	<rule ref="WordPress.PHP.RestrictedPHPFunctions"/>
+
 
 	<!--
 	#############################################################################
@@ -368,6 +421,12 @@
 	<!-- All files should end with a new line. -->
 	<rule ref="Generic.Files.EndFileNewline"/>
 
+	<!-- No whitespace should come before semicolons. -->
+	<!-- Extends upstream sniff. Should defer to upstream version once minimum PHPCS requirement
+		 has gone up to version containing bugfix.
+		 https://github.com/squizlabs/PHP_CodeSniffer/pull/1691 -->
+	<rule ref="WordPress.WhiteSpace.SemicolonSpacing"/>
+
 	<!-- Lowercase PHP constants, like true, false and null. -->
 	<!-- http://make.wordpress.org/core/handbook/coding-standards/php/#naming-conventions -->
 	<rule ref="Generic.PHP.LowerCaseConstant"/>
@@ -378,6 +437,13 @@
 	<!-- Class opening braces should be on the same line as the statement. -->
 	<rule ref="Generic.Classes.OpeningBraceSameLine"/>
 
+	<!-- Object operators should not have whitespace around them unless they are multi-line. -->
+	<rule ref="Squiz.WhiteSpace.ObjectOperatorSpacing">
+		<properties>
+			<property name="ignoreNewlines" value="true"/>
+		</properties>
+	</rule>
+
 	<!-- References to self in a class should be lower-case and not have extraneous spaces,
 		 per implicit conventions in the core codebase; the NotUsed code refers to using the
 		 fully-qualified class name instead of self, for which there are instances in core. -->