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

Releasing version 0.10.0

.travis.yml

@@ -9,19 +9,26 @@ php:
     - 5.4
     - 5.5
     - 5.6
+    - 7.0
 
 env:
   - PHPCS_BRANCH=master
-  - PHPCS_BRANCH=2.2.0
+  - PHPCS_BRANCH=2.6.0
 
 matrix:
   fast_finish: true
   include:
+    # Run PHPCS against WPCS. I just picked to run it against 5.5.
+    - php: 5.5
+      env: PHPCS_BRANCH=master SNIFF=1
     # Run against PHPCS 3.0. I just picked to run it against 5.6.
     - php: 5.6
       env: PHPCS_BRANCH=3.0
     # Run against HHVM and PHP nightly.
     - php: hhvm
+      sudo: required
+      dist: trusty 
+      group: edge 
       env: PHPCS_BRANCH=master
     - php: nightly
       env: PHPCS_BRANCH=master
@@ -32,6 +39,7 @@ matrix:
     - 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
     - export PHPCS_DIR=/tmp/phpcs
     - 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
@@ -40,3 +48,13 @@ before_script:
 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
+    # 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_DIR/scripts/phpcs -p -s -v -n . --standard=./bin/phpcs.xml --extensions=php; fi

CHANGELOG.md

@@ -6,8 +6,61 @@ This projects adheres to [Semantic Versioning](http://semver.org/) and [Keep a C
 
 ## [Unreleased]
 
+_Nothing yet._
+
+## [0.10.0] - 2016-08-29
+
 ### Added
-- Sniff to flag dynamic translatable strings and textdomains.
+- `WordPress.WP.I18n` sniff to the `WordPress-Core` ruleset to flag dynamic translatable strings and textdomains.
+- `WordPress.PHP.DisallowAlternativePHPTags` sniff to the `WordPress-Core` ruleset to flag - and fix - ASP and `<script>` PHP open tags.
+- `WordPress.Classes.ClassOpeningStatement` sniff to the `WordPress-Core` ruleset to flag - and fix - class opening brace placement.
+- `WordPress.NamingConventions.ValidHookName` sniff to the `WordPress-Core` ruleset to flag filter and action hooks which don't comply with the guideline of lowercase letters and underscores. For maintaining backward-compatibility of hook names an `additionalWordDelimiters` property can be added via a custom ruleset.
+- `WordPress.Functions.DontExtract` sniff to the `WordPress-Core` ruleset to flag usage of the `extract()` function.
+- `WordPress.PHP.POSIXFunctions` sniff to the `WordPress-Core` ruleset to flag usage of regex functions from the POSIX PHP extension which was deprecated since PHP 5.3 and removed in PHP 7.
+- `WordPress.DB.RestrictedFunctions` and `WordPress.DB.RestrictedClasses` sniffs to the `WordPress-Core` ruleset to flag usage of direct database calls using PHP functions and classes rather than the WP functions for the same.
+- Abstract `AbstractClassRestrictions` parent class to allow for easier sniffing for usage of specific classes.
+- `Squiz.Strings.ConcatenationSpacing`, `PSR2.ControlStructures.ElseIfDeclaration`, `PSR2.Files.ClosingTag`, `Generic.NamingConventions.UpperCaseConstantName` to the `WordPress-Core` ruleset.
+- Ability to add arbitrary variables to the whitelist via a custom ruleset property for the `WordPress.NamingConventions.ValidVariableName` sniff.
+- Ability to use a whitelist comment for tax queries for the `WordPress.VIP.SlowDBQuery` sniff.
+- Instructions on how to use WPCS with Atom and SublimeLinter to the Readme.
+- Reference to the [wiki](https://github.com/WordPress-Coding-Standards/WordPress-Coding-Standards/wiki) to the Readme.
+- Recommendation to also use the [PHPCompatibility](https://github.com/wimg/PHPCompatibility) ruleset to the Readme.
+
+### Changed
+- The minimum required PHP_CodeSniffer version to 2.6.0.
+- Moved the `WordPress.WP.PreparedSQL` sniff from `WordPress-Extra` to `WordPress-Core`.
+- `WordPress.PHP.StrictInArray` will now also flag non-strict usage of `array_keys()` and `array_search()`.
+- Added `_deprecated_constructor()` and `_deprecated_hook()` to the list of printing functions.
+- Added numerous additional functions to sniff for to the `WordPress.VIP.RestrictedFunctions` sniff as per the VIP guidelines.
+- Upped the `posts_per_page` limit from 50 to 100 in `WordPress.VIP.PostsPerPage` sniff as per the VIP guidelines.
+- Added `cat_ID` to the whitelisted exceptions for the `WordPress.NamingConventions.ValidVariableName` sniff.
+- Added `__debugInfo` to the magic method whitelist for class methods starting with double underscore in the `WordPress.NamingConventions.ValidFunctionName` sniff.
+- An error will now also be thrown for non-magic _functions_ using a double underscore prefix - `WordPress.NamingConventions.ValidFunctionName` sniff.
+- The `WordPress.Arrays.ArrayAssignmentRestrictions`, `WordPress.Functions.FunctionRestrictions`, `WordPress.Variables.VariableRestrictions` sniffs weren't in actual fact sniffs, but parent classes for child sniffs. These have now all been turned into proper abstract parent classes and moved to the main `WordPress` directory.
+- The array provided to `AbstractFunctionRestrictions` can now take a `whitelist` key to whitelist select functions when blocking a group of functions by function prefix.
+- Updated installation instructions in the readme.
+- The `WordPress-Core` ruleset is now ordered according to the handbook
+- The WPCS code base itself now complies with the WordPress-Core, -Extra and -Docs coding standards.
+- Various other code quality and code consistency improvements under the hood.
+
+### Removed
+- `Squiz.Functions.FunctionDeclarationArgumentSpacing.SpacingBeforeClose` from the `WordPress-Core` standard (was causing duplicate messages for the same issue).
+- `Squiz.Commenting.FunctionComment.ScalarTypeHintMissing`, `Squiz.Commenting.InlineComment.NotCapital` from the `WordPress-Docs` standard.
+- Removed the sniffing for `get_pages()` from the `WordPress.VIP.RestrictedFunctions` sniff as per the VIP guidelines.
+- Removed the sniffing for `extract()` from the `WordPress.VIP.RestrictedFunctions` sniff as it's now covered in a separate sniff.
+- Removed the sniffing for the POSIX functions from the `WordPress.PHP.DiscouragedFunctions` sniff as it's now covered in a separate sniff.
+
+### Fixed
+- Error message precision for the `WordPress.NamingConventions.ValidVariableName` sniff.
+- Bug in the `WordPress.WhiteSpace.ControlStructureSpacing.BlankLineAfterEnd` sniff which was incorrectly being triggered on last method of class.
+- Function name sniffs based on the `AbstractFunctionRestrictions` parent class will now do a case-insensitive function name comparison.
+- Function name sniffs in the `WordPress.PHP.DiscouragedFunctions` sniff will now do a case-insensitive function name comparison.
+- Whitelist comments directly followed by a PHP closing tag were not being recognized.
+- Some PHP Magic constants were not recognized by the `WordPress.XSS.EscapeOutput` sniff.
+- An error message suggesting camel caps rather than the intended snake case format in the `WordPress.NamingConventions.ValidFunctionName` sniff.
+- `WordPress.WhiteSpace.ControlStructureSpacing` should no longer throw error notices during live code review.
+- Errors will be no longer be thrown for methods not complying with the naming conventions when the class extends a parent class or implements an interface - `WordPress.NamingConventions.ValidFunctionName` sniff.
+
 
 ## [0.9.0] - 2016-02-01
 
@@ -191,7 +244,8 @@ See the comparison for full list.
 
 Initial tagged release.
 
-[Unreleased]: https://github.com/WordPress-Coding-Standards/WordPress-Coding-Standards/compare/0.9.0...HEAD
+[Unreleased]: https://github.com/WordPress-Coding-Standards/WordPress-Coding-Standards/compare/0.10.0...HEAD
+[0.10.0]: https://github.com/WordPress-Coding-Standards/WordPress-Coding-Standards/compare/0.9.0...0.10.0
 [0.9.0]: https://github.com/WordPress-Coding-Standards/WordPress-Coding-Standards/compare/0.8.0...0.9.0
 [0.8.0]: https://github.com/WordPress-Coding-Standards/WordPress-Coding-Standards/compare/0.7.1...0.8.0
 [0.7.1]: https://github.com/WordPress-Coding-Standards/WordPress-Coding-Standards/compare/0.7.0...0.7.1

CONTRIBUTING.md

@@ -1,3 +1,7 @@
+# Upstream Issues
+
+Since WPCS employs many sniffs that are part of PHPCS, sometimes an issue will be caused by a bug in PHPCS and not in WPCS itself. Before reporting a bug, you should check what sniff an error is coming from. Running `phpcs` with the `-s` flag, which will show the names of the sniffs with each error. If the error message in question doesn't come from a sniff whose name starts with `WordPress`, the issue is probably a bug in PHPCS itself, and should be [reported there](https://github.com/squizlabs/PHP_CodeSniffer/issues).
+
 # Branches
 
 Ongoing development will be done in the `develop` with merges done into `master` once considered stable.
@@ -10,23 +14,25 @@ Once a commit is made to `develop`, a PR should be opened from `develop` into `m
 
 TL;DR
 
-Make sure you have `phpunit` installed and available in your `PATH`. If you have installed `phpcs` and the WordPress-Coding-Standards as [noted in the README](https://github.com/WordPress-Coding-Standards/WordPress-Coding-Standards#how-to-use-this), then you can navigate to the directory where the `phpcs` repo is checked out and do:
+If you have installed `phpcs` and the WordPress-Coding-Standards as [noted in the README](https://github.com/WordPress-Coding-Standards/WordPress-Coding-Standards#how-to-use-this), then you can navigate to the directory where the `phpcs` repo is checked out and do:
 
-```bash
-git checkout phpcs-fixer # needed temporarily until PHPCS 2.0
-phpunit --filter WordPress tests/AllTests.php
+```sh
+composer install
+vendor/bin/phpunit --filter WordPress tests/AllTests.php
 ```
 
 Expected output:
 
-~~~text
-PHPUnit 3.7.18 by Sebastian Bergmann.
+~~~sh
+PHPUnit 4.8.26 by Sebastian Bergmann and contributors.
+
+....................................
 
-...............
+Tests generated 90 unique error codes; 28 were fixable (31.11%)
 
-Time: 1 second, Memory: 37.00Mb
+Time: 3.08 second, Memory: 24.00MB
 
-OK (15 tests, 0 assertions)
+OK (36 tests, 0 assertions)
 ~~~
 
 You can ignore any skipped tests as these are for `PHP_CodeSniffer` external tools.
@@ -66,7 +72,7 @@ Also note the class name convention. The method `getErrorList` MUST return an ar
 indicating errors (when running `phpcs`) found in `WordPress/Tests/Arrays/ArrayDeclarationUnitTest.inc`.
 If you run:
 
-~~~text
+~~~sh
 $ cd /path-to-cloned/phpcs
 $ ./scripts/phpcs --standard=Wordpress -s CodeSniffer/Standards/WordPress/Tests/Arrays/ArrayDeclarationUnitTest.inc
 ...

README.md

@@ -67,22 +67,25 @@ Run the `phpcs` command line tool on a given file or directory, for example:
 Will result in following output:
 
 	--------------------------------------------------------------------------------
-	FOUND 13 ERROR(S) AFFECTING 7 LINE(S)
+	FOUND 8 ERRORS AND 2 WARNINGS AFFECTING 7 LINES
 	--------------------------------------------------------------------------------
-	  1 | ERROR | End of line character is invalid; expected "\n" but found "\r\n"
-	 22 | ERROR | No space after opening parenthesis of function  prohibited
-	 22 | ERROR | No space before closing parenthesis of function  prohibited
-	 26 | ERROR | No space before closing parenthesis of function  prohibited
-	 31 | ERROR | No space after opening parenthesis of function  prohibited
-	 31 | ERROR | No space before closing parenthesis of function  prohibited
-	 31 | ERROR | No space after opening parenthesis of function  prohibited
-	 31 | ERROR | No space before closing parenthesis of function  prohibited
-	 34 | ERROR | No space after opening parenthesis of function  prohibited
-	 34 | ERROR | No space before closing parenthesis of function  prohibited
-	 55 | ERROR | Detected usage of a non-validated input variable: $_SERVER
-	 55 | ERROR | Detected usage of a non-sanitized input variable: $_SERVER
-	 70 | ERROR | String "Create a Configuration File" does not require double
-		|       | quotes; use single quotes instead
+	  1 | ERROR   | [x] End of line character is invalid; expected "\n" but found "\r\n"
+	 36 | ERROR   | [x] Expected 1 spaces before closing bracket; 0 found
+	 41 | WARNING | [ ] Silencing errors is discouraged
+	 41 | WARNING | [ ] Silencing errors is discouraged
+	 48 | ERROR   | [ ] Inline comments must end in full-stops, exclamation marks, or
+	    |         |     question marks
+	 48 | ERROR   | [x] There must be no blank line following an inline comment
+	 76 | ERROR   | [ ] Inline comments must end in full-stops, exclamation marks, or
+	    |         |     question marks
+	 92 | ERROR   | [x] String "Create a Configuration File" does not require double
+	    |         |     quotes; use single quotes instead
+	 94 | ERROR   | [ ] Expected next thing to be an escaping function (see Codex for
+	    |         |     'Data Validation'), not '$die'
+	 94 | ERROR   | [ ] Expected next thing to be an escaping function (see Codex for
+	    |         |     'Data Validation'), not '__'
+	--------------------------------------------------------------------------------
+	PHPCBF CAN FIX THE 4 MARKED SNIFF VIOLATIONS AUTOMATICALLY
 	--------------------------------------------------------------------------------
 
 ### PhpStorm
@@ -91,8 +94,35 @@ Please see “[PHP Code Sniffer with WordPress Coding Standards Integration](htt
 
 ### Sublime Text
 
+##### sublime-phpcs package
 Install the [sublime-phpcs package](https://github.com/benmatselby/sublime-phpcs), then use the "Switch coding standard" command in the Command Palette to switch between coding standards.
 
+##### SublimeLinter-phpcs
+sublime-phpcs is insanely powerful, but if you'd prefer automatic linting, [SublimeLinter-phpcs](https://github.com/SublimeLinter/SublimeLinter-phpcs/) can do that.
+
+- Install PHP Sniffer and WordPress Coding Standards per above.
+- Use [Package Control](https://packagecontrol.io/) to search for and install [SublimeLinter](http://www.sublimelinter.com) then [SublimeLinter-phpcs](https://github.com/SublimeLinter/SublimeLinter-phpcs/).
+- From the command palette, select `Preferences: SublimeLinter Settings - User` and change `user.linters.phpcs.standard` to the phpcs standard of your choice (e.g. `WordPress`, `WordPress-VIP`, etc.).
+
+![SublimeLinter-phpcs user settings](https://cloud.githubusercontent.com/assets/224636/12946250/068776ba-cfc1-11e5-816b-109e4e32d21b.png)
+
+- You may need to restart Sublime for these settings to take effect. Error messages appear in the bottom of the editor.
+
+![SublimeLinter-phpcs linting](https://cloud.githubusercontent.com/assets/224636/12946326/75986c3a-cfc1-11e5-8537-1243554bbab6.png)
+
+![SublimeLinter-phpcs error](https://cloud.githubusercontent.com/assets/224636/12946335/8bee5a30-cfc1-11e5-8b5f-b10e8e4a4909.png)
+
+### Atom
+
+- 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.).
+
+![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)
+
 ## 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.
@@ -108,10 +138,27 @@ You can use the following as standard names when invoking `phpcs` to select snif
     - includes `WordPress-Core`
 
 
-### Using custom ruleset
+### Using a custom ruleset
 
 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.
 
+### 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)
+
+## Fixing errors or whitelisting them
+
+You can find information on how to deal with some of the more frequent issues in the [wiki](https://github.com/WordPress-Coding-Standards/WordPress-Coding-Standards/wiki).
+
+
 ## Contributing
 
 See [CONTRIBUTING](CONTRIBUTING.md), including information about [unit testing](CONTRIBUTING.md#unit-testing).