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

Release 0.11.0
WordPress · Mar 20, 2017 · 407e4b8 · 407e4b8
2 parents b394904 + 3e1b17e
commit 407e4b8
Show file tree

Hide file tree

Showing 171 changed files with 8,068 additions and 3,409 deletions.
diff --git a/.travis.yml b/.travis.yml
@@ -10,10 +10,11 @@ php:
     - 5.5
     - 5.6
     - 7.0
+    - 7.1
 
 env:
   - PHPCS_BRANCH=master
-  - PHPCS_BRANCH=2.6.0
+  - PHPCS_BRANCH=2.8.1
 
 matrix:
   fast_finish: true
@@ -38,16 +39,20 @@ matrix:
     - php: hhvm
     - env: PHPCS_BRANCH=3.0
 
-before_script:
-    - if [[ $TRAVIS_PHP_VERSION != "7.0" && $TRAVIS_PHP_VERSION != "nightly" && $TRAVIS_PHP_VERSION != "hhvm" ]]; then phpenv config-add myconfig.ini; fi
+before_install:
     - export PHPCS_DIR=/tmp/phpcs
+    - export PHPUNIT_DIR=/tmp/phpunit
     - export PHPCS_BIN=$(if [[ $PHPCS_BRANCH == 3.0 ]]; 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
+    # PHPCS test suite is currently not compatible with PHPUnit 6.x.
+    - if [[ ${TRAVIS_PHP_VERSION:0:2} != "5." ]]; then wget -P $PHPUNIT_DIR https://phar.phpunit.de/phpunit-5.7.phar && chmod +x $PHPUNIT_DIR/phpunit-5.7.phar; fi
 
 script:
     - if find . -name "*.php" -exec php -l {} \; | grep "^[Parse error|Fatal error]"; then exit 1; fi;
-    - phpunit --filter WordPress /tmp/phpcs/tests/AllTests.php
+    - if [[ ${TRAVIS_PHP_VERSION:0:2} == "5." ]]; then phpunit --filter WordPress /tmp/phpcs/tests/AllTests.php; fi
+    - if [[ ${TRAVIS_PHP_VERSION:0:2} != "5." ]]; then php $PHPUNIT_DIR/phpunit-5.7.phar --filter WordPress /tmp/phpcs/tests/AllTests.php; fi
     # WordPress Coding Standards.
     # @link https://github.com/WordPress-Coding-Standards/WordPress-Coding-Standards
     # @link http://pear.php.net/package/PHP_CodeSniffer/
@@ -57,4 +62,4 @@ script:
     # -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_DIR/scripts/phpcs -p -s -v -n . --standard=./bin/phpcs.xml --extensions=php; fi
+    - if [[ "$SNIFF" == "1" ]]; then $PHPCS_DIR/scripts/phpcs -p -s -n . --standard=./bin/phpcs.xml --extensions=php; fi
diff --git a/CHANGELOG.md b/CHANGELOG.md
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -10,6 +10,42 @@ To contribute an improvement to this project, fork the repo and open a pull requ
 
 Once a commit is made to `develop`, a PR should be opened from `develop` into `master` and named "Next release". This PR will then serve provide a second round of Travis CI checks (especially for any hotfixes pushed directly to the `develop` branch), and provide collaborators with a forum to discuss the upcoming stable release.
 
+# Considerations when writing sniffs
+
+## Public properties
+
+When writing sniffs, always remember that any `public` sniff property can be overruled via a custom ruleset by the end-user.
+Only make a property `public` if that is the intended behaviour.
+
+When you introduce new `public` sniff properties, or your sniff extends a class from which you inherit a `public` property, please don't forget to update the [public properties wiki page](https://github.com/WordPress-Coding-Standards/WordPress-Coding-Standards/wiki/Customizable-sniff-properties) with the relevant details once your PR has been merged into the `develop` branch.
+
+## Whitelist comments
+
+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
+class WordPress_Sniffs_CSRF_NonceVerificationSniff extends WordPress_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.
+
+
 # Unit Testing
 
 TL;DR
@@ -23,17 +59,7 @@ vendor/bin/phpunit --filter WordPress tests/AllTests.php
 
 Expected output:
 
-~~~sh
-PHPUnit 4.8.26 by Sebastian Bergmann and contributors.
-
-....................................
-
-Tests generated 90 unique error codes; 28 were fixable (31.11%)
-
-Time: 3.08 second, Memory: 24.00MB
-
-OK (36 tests, 0 assertions)
-~~~
+[![asciicast](https://asciinema.org/a/98078.png)](https://asciinema.org/a/98078)
 
 You can ignore any skipped tests as these are for `PHP_CodeSniffer` external tools.
 
@@ -49,7 +75,7 @@ the `WordPress/Sniffs/Arrays/ArrayDeclarationSniff.php` sniff has unit test clas
 `WordPress/Tests/Arrays/ArrayDeclarationUnitTest.php` that check `WordPress/Tests/Arrays/ArrayDeclarationUnitTest.inc`
 file. See the file naming convention? Lets take a look what inside `ArrayDeclarationUnitTest.php`:
 
-~~~php
+```php
 ...
 class WordPress_Tests_Arrays_ArrayDeclarationUnitTest extends AbstractSniffUnitTest
 {
@@ -66,13 +92,13 @@ class WordPress_Tests_Arrays_ArrayDeclarationUnitTest extends AbstractSniffUnitT
     }//end getErrorList()
 }
 ...
-~~~
+```
 
 Also note the class name convention. The method `getErrorList` MUST return an array of line numbers
 indicating errors (when running `phpcs`) found in `WordPress/Tests/Arrays/ArrayDeclarationUnitTest.inc`.
 If you run:
 
-~~~sh
+```sh
 $ cd /path-to-cloned/phpcs
 $ ./scripts/phpcs --standard=Wordpress -s CodeSniffer/Standards/WordPress/Tests/Arrays/ArrayDeclarationUnitTest.inc
 ...
@@ -101,7 +127,7 @@ FOUND 8 ERROR(S) AND 2 WARNING(S) AFFECTING 6 LINE(S)
     |         | (WordPress.WhiteSpace.OperatorSpacing)
 --------------------------------------------------------------------------------
 ....
-~~~
+```
 
 You'll see the line number and number of ERRORs we need to return in `getErrorList` method.
 In line #31 there are two ERRORs belong to `WordPress.WhiteSpace.OperatorSpacing` sniff and

diff --git a/README.md b/README.md
@@ -1,26 +1,59 @@
 [![Build Status](https://travis-ci.org/WordPress-Coding-Standards/WordPress-Coding-Standards.png?branch=master)](https://travis-ci.org/WordPress-Coding-Standards/WordPress-Coding-Standards)
+[![Total Downloads](https://poser.pugx.org/wp-coding-standards/wpcs/downloads)](https://packagist.org/packages/wp-coding-standards/wpcs)
 
 # WordPress Coding Standards for PHP_CodeSniffer
 
+* [Introduction](#introduction)
+* [Project history](#project-history)
+* [Installation](#installation)
+    + [Requirements](#requirements)
+    + [Composer](#composer)
+    + [Standalone](#standalone)
+* [Rulesets](#rulesets)
+    + [Standards subsets](#standards-subsets)
+    + [Using a custom ruleset](#using-a-custom-ruleset)
+    + [Customizing sniff behaviour](#customizing-sniff-behaviour)
+    + [Recommended additional rulesets](#recommended-additional-rulesets)
+* [How to use](#how-to-use)
+    + [Command line](#command-line)
+    + [PhpStorm](#phpstorm)
+    + [Sublime Text](#sublime-text)
+    + [Atom](#atom)
+    + [Visual Studio](#visual-studio)
+* [Running your code through WPCS automatically using CI tools](#running-your-code-through-wpcs-automatically-using-ci-tools)
+    + [[Travis CI](https://travis-ci.org/)](#-travis-ci--https---travis-ciorg--)
+* [Fixing errors or whitelisting them](#fixing-errors-or-whitelisting-them)
+* [Contributing](#contributing)
+* [License](#license)
+
+## Introduction
+
 This project is a collection of [PHP_CodeSniffer](https://github.com/squizlabs/PHP_CodeSniffer) rules (sniffs) to validate code developed for WordPress. It ensures code quality and adherence to coding conventions, especially the official [WordPress Coding Standards](http://make.wordpress.org/core/handbook/coding-standards/).
 
 ## Project history
 
  - In April 2009 original project from [Urban Giraffe](http://urbangiraffe.com/articles/wordpress-codesniffer-standard/) was published.
  - In May 2011 the project was forked on GitHub by [Chris Adams](http://chrisadams.me.uk/).
- - In April 2012 [XWP](https://xwp.co/) started to dedicate resources to the development and currently maintains the project, along with [J.D. Grimes](https://github.com/JDGrimes) and [Gary Jones](https://github.com/GaryJones).
+ - In April 2012 [XWP](https://xwp.co/) started to dedicate resources to development and lead creation of the the sniffs and rulesets for `WordPress-Core`, `WordPress-VIP` (WordPress.com VIP), and `WordPress-Extra`.
+ - In 2015, [J.D. Grimes](https://github.com/JDGrimes) began significant contributions, along with maintanance from [Gary Jones](https://github.com/GaryJones).
+ - In 2016, [Juliette Reinders Folmer](https://github.com/jrfnl) began contributing heavily, adding more commits in a year than anyone else in 5 years previous since the project's inception.
 
 ## Installation
 
+### Requirements
+
+The WordPress Coding Standards require PHP 5.2 or higher and the [PHP_CodeSniffer](https://github.com/squizlabs/PHP_CodeSniffer) version **2.8.1** or higher.
+The WordPress Coding Standards are currently [not compatible with the upcoming PHPCS 3 release](https://github.com/WordPress-Coding-Standards/WordPress-Coding-Standards/issues/718).
+
 ### Composer
 
 Standards can be installed with [Composer](https://getcomposer.org/) dependency manager:
 
-    composer create-project wp-coding-standards/wpcs:dev-master --no-dev
+    composer create-project wp-coding-standards/wpcs --no-dev
 
 Running this command will:
 
-1. Install WordPress standards into `wpcs` directory.  
+1. Install WordPress standards into `wpcs` directory.
 2. Install PHP_CodeSniffer.
 3. Register WordPress standards in PHP_CodeSniffer configuration.
 4. Make `phpcs` command available from `wpcs/vendor/bin`.
@@ -31,7 +64,7 @@ For convenience of using `phpcs` as global command you might want to add path to
 
 1. Install PHP_CodeSniffer by following its [installation instructions](https://github.com/squizlabs/PHP_CodeSniffer#installation) (via Composer, PEAR, or Git checkout).
 
-  Do ensure, if for example you're using [VVV](https://github.com/Varying-Vagrant-Vagrants/VVV), that PHP_CodeSniffer's version matches our requirements (you can check the required version in [composer.json](composer.json#L18)).
+   Do ensure, if for example you're using [VVV](https://github.com/Varying-Vagrant-Vagrants/VVV), that PHP_CodeSniffer's version matches our [requirements](#requirements).
 
 2. Clone WordPress standards repository:
 
@@ -56,6 +89,44 @@ And then add the `~/projects/phpcs/scripts` directory to your `PATH` environment
 
 You should then see `WordPress-Core` et al listed when you run `phpcs -i`.
 
+##  Rulesets
+
+### Standards subsets
+
+The project encompasses a super–set of the sniffs that the WordPress community may need. If you use the `WordPress` standard you will get all the checks. Some of them might be unnecessary for your environment, for example those specific to WordPress VIP coding requirements.
+
+You can use the following as standard names when invoking `phpcs` to select sniffs, fitting your needs:
+
+* `WordPress` — complete set with all of the sniffs in the project
+  - `WordPress-Core` — main ruleset for [WordPress core coding standards](http://make.wordpress.org/core/handbook/coding-standards/)
+  - `WordPress-Docs` — additional ruleset for [WordPress inline documentation standards](https://make.wordpress.org/core/handbook/best-practices/inline-documentation-standards/)
+  - `WordPress-Extra` — extended ruleset for recommended best practices, not sufficiently covered in the WordPress core coding standards
+    - includes `WordPress-Core`
+  - `WordPress-VIP` — extended ruleset for [WordPress VIP coding requirements](http://vip.wordpress.com/documentation/code-review-what-we-look-for/)
+    - includes `WordPress-Core`
+
+### Using a custom ruleset
+
+If you need to further customize the selection of sniffs for your project — you can create a custom `phpcs.xml` standard. See provided [project.ruleset.xml.example](project.ruleset.xml.example) file and [fully annotated example](https://github.com/squizlabs/PHP_CodeSniffer/wiki/Annotated-ruleset.xml) in PHP_CodeSniffer documentation.
+
+### Customizing sniff behaviour
+
+The WordPress Coding Standard contains a number of sniffs which are configurable. This means that you can turn parts of the sniff on or off, or change the behaviour by setting a property for the sniff in your custom `ruleset.xml` file.
+
+You can find a complete list of all the properties you can change in the [wiki](https://github.com/WordPress-Coding-Standards/WordPress-Coding-Standards/wiki/Customizable-sniff-properties).
+
+### Recommended additional rulesets
+
+The [PHPCompatibility](https://github.com/wimg/PHPCompatibility) ruleset comes highly recommended.
+The [PHPCompatibility](https://github.com/wimg/PHPCompatibility) sniffs are designed to analyse your code for cross-PHP version compatibility.
+Install it as a separate ruleset and either run it separately against your code or add it to your custom ruleset.
+
+Whichever way you run it, do make sure you set the `testVersion` to run the sniffs against. The `testVersion` determines for which PHP versions you will received compatibility information. The recommended setting for this at this moment is  `5.2-7.1` to support the same PHP versions as WordPress Core supports.
+
+For more information about setting the `testVersion`, see:
+* [PHPCompatibility: Using the compatibility sniffs](https://github.com/wimg/PHPCompatibility#using-the-compatibility-sniffs)
+* [PHPCompatibility: Using a custom ruleset](https://github.com/wimg/PHPCompatibility#using-a-custom-ruleset)
+
 ## How to use
 
 ### Command line
@@ -123,36 +194,52 @@ sublime-phpcs is insanely powerful, but if you'd prefer automatic linting, [Subl
 
 ![Atom Linter in action using WordPress Coding Standards](https://cloud.githubusercontent.com/assets/224636/12740542/131c5894-c942-11e5-9e31-5e020c993224.png)
 
-## Standards subsets
+### Visual Studio
 
-The project encompasses a super–set of the sniffs that the WordPress community may need. If you use the `WordPress` standard you will get all the checks. Some of them might be unnecessary for your environment, for example those specific to WordPress VIP coding requirements.
+Please see “[Setting up PHP CodeSniffer in Visual Studio Code](https://tommcfarlin.com/php-codesniffer-in-visual-studio-code/)”, a tutorial by Tom McFarlin.
 
-You can use the following as standard names when invoking `phpcs` to select sniffs, fitting your needs:
 
- - `WordPress` — complete set with all of the sniffs in the project
-  - `WordPress-Core` — main ruleset for [WordPress core coding standards](http://make.wordpress.org/core/handbook/coding-standards/)
-  - `WordPress-Docs` — additional ruleset for inline documentation
-  - `WordPress-Extra` — extended ruleset for optional best practices sniffs
-    - includes `WordPress-Core`
-  - `WordPress-VIP` — extended ruleset for [WordPress VIP coding requirements](http://vip.wordpress.com/documentation/code-review-what-we-look-for/)
-    - includes `WordPress-Core`
+## Running your code through WPCS automatically using CI tools
 
+### [Travis CI](https://travis-ci.org/)
 
-### Using a custom ruleset
+To integrate PHPCS with WPCS with Travis CI, you'll need to install both `before_install` and add the run command to the `script`.
+If your project uses Composer, the typical instructions might be different.
 
-If you need to further customize selection of sniffs for your project — you can create custom `ruleset.xml` standard. See provided [project.ruleset.xml.example](project.ruleset.xml.example) file and [fully annotated example](https://github.com/squizlabs/PHP_CodeSniffer/wiki/Annotated-ruleset.xml) in PHP_CodeSniffer documentation.
+If you use a matrix setup in Travis to test your code against different PHP and/or WordPress versions, you don't need to run PHPCS on each variant of the matrix as the results will be same.
+You can set an environment variable in the Travis matrix to only run the sniffs against one setup in the matrix.
 
-### Recommended additional rulesets
+#### Travis CI example
+```yaml
+language: php
 
-The [PHPCompatibility](https://github.com/wimg/PHPCompatibility) ruleset comes highly recommended.
-The [PHPCompatibility](https://github.com/wimg/PHPCompatibility) sniffs are designed to analyse your code for cross-PHP version compatibility.
-Install it as a separate ruleset and either run it separately against your code or add it to your custom ruleset.
+matrix:
+  include:
+    # Arbitrary PHP version to run the sniffs against.
+    - php: '7.0'
+      env: SNIFF=1
 
-Whichever way you run it, do make sure you set the `testVersion` to run the sniffs against. The `testVersion` determines for which PHP versions you will received compatibility information. The recommended setting for this at this moment is  `5.2-7.1` to support the same PHP versions as WordPress Core supports.
+before_install:
+  - if [[ "$SNIFF" == "1" ]]; export PHPCS_DIR=/tmp/phpcs; fi
+  - if [[ "$SNIFF" == "1" ]]; export SNIFFS_DIR=/tmp/sniffs; fi
+  # 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
+  # Set install path for WordPress Coding Standards.
+  - if [[ "$SNIFF" == "1" ]]; then $PHPCS_DIR/scripts/phpcs --config-set installed_paths $SNIFFS_DIR; fi
+  # After CodeSniffer install you should refresh your path.
+  - if [[ "$SNIFF" == "1" ]]; then phpenv rehash; fi
+
+script:
+  # Run against WordPress Coding Standards.
+  # If you use a custom ruleset, change `--standard=WordPress` to point to your ruleset file,
+  # for example: `--standard=wpcs.xml`.
+  # You can use any of the normal PHPCS command line arguments in the command:
+  # https://github.com/squizlabs/PHP_CodeSniffer/wiki/Usage
+  - if [[ "$SNIFF" == "1" ]]; then $PHPCS_DIR/scripts/phpcs -p . --standard=WordPress; fi
+```
 
-For more information about setting the `testVersion`, see:
-* [PHPCompatibility: Using the compatibility sniffs](https://github.com/wimg/PHPCompatibility#using-the-compatibility-sniffs)
-* [PHPCompatibility: Using a custom ruleset](https://github.com/wimg/PHPCompatibility#using-a-custom-ruleset)
 
 ## Fixing errors or whitelisting them