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

Release version 1.2.0

.github/CONTRIBUTING.md

@@ -2,6 +2,8 @@ Hi, thank you for your interest in contributing to the WordPress Coding Standard
 
 # Reporting Bugs
 
+Please search the repo to see if your issue has been reported already and if so, comment in that issue instead of opening a new one.
+
 Before reporting a bug, you should check what sniff an error is coming from.
 Running `phpcs` with the `-s` flag will show the name of the sniff with each error.
 

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,47 @@
+---
+name: Bug report
+about: Create a report to help us improve
+
+---
+
+## Bug Description
+<!--
+Please provide a clear and concise description of what the bug is.
+
+What did you expect to happen? What actually happened?
+-->
+
+## Minimal Code Snippet
+<!-- Please provide example code that demonstrates the issue. Do NOT paste screenshots of code! -->
+
+```php
+// Place your code sample here.
+```
+
+For bugs with fixers: How was the code fixed? How did you expect the code to be fixed?
+
+## Error Code
+<!--
+The error code for the sniff that is (or should be) being triggered (you
+can see the sniff error codes by running `phpcs` with the `-s` flag).
+e.g. `WordPress.PHP.NoSilencedErrors.Discouraged`
+
+You can leave this section empty if you are reporting a false negative.
+-->
+
+## Environment
+
+| Question               | Answer
+| ------------------------| -------
+| PHP version             | x.y.z 
+| PHP_CodeSniffer version | x.y.z
+| WPCS version            | x.y.z
+| WPCS install type       | e.g. Composer global, Composer project local, git clone, other (please expand)
+| IDE (if relevant)       | Name and version e.g. PhpStorm 2018.2.2
+
+
+## Additional Context (optional)
+<!-- Add any other context about the problem here. -->
+
+## Tested Against `develop` branch?
+- [ ] I have verified the issue still exists in the `develop` branch of WPCS.

.github/ISSUE_TEMPLATE/dependency-change.md

@@ -0,0 +1,21 @@
+---
+name: Dependency Change
+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: ... -->
+
+## Rationale
+
+<!-- Why should this change be made in WPCS? -->
+
+## References
+
+<!-- References, like a link to the changelog of the version which contains a feature or the upstream issue which requested it -->
+
+ -  ...
+
+## Action Checklist
+
+- [ ] ...

.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,19 @@
+---
+name: Feature request
+about: Suggest an idea for this project
+
+---
+
+## Is your feature request related to a problem?
+<!-- A clear and concise description of what the problem is. Ex. I'm always frustrated when [...] -->
+
+## Describe the solution you'd like
+<!--
+A clear and concise description of what you want to happen.
+
+Any (sniff) feature request/suggestion should be accompanied by code samples of what should be detected.
+And preferably also code samples of code which shouldn't be flagged.
+-->
+
+## Additional context (optional)
+<!-- Add any other context or screenshots about the feature request here. -->

.phpcs.xml.dist

@@ -38,18 +38,18 @@
 	<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"/>
+		<exclude name="PHPCompatibility.Constants.NewConstants.t_finallyFound"/>
+		<exclude name="PHPCompatibility.Constants.NewConstants.t_yieldFound"/>
+		<exclude name="PHPCompatibility.Constants.NewConstants.t_ellipsisFound"/>
+		<exclude name="PHPCompatibility.Constants.NewConstants.t_powFound"/>
+		<exclude name="PHPCompatibility.Constants.NewConstants.t_pow_equalFound"/>
+		<exclude name="PHPCompatibility.Constants.NewConstants.t_spaceshipFound"/>
+		<exclude name="PHPCompatibility.Constants.NewConstants.t_coalesceFound"/>
+		<exclude name="PHPCompatibility.Constants.NewConstants.t_coalesce_equalFound"/>
+		<exclude name="PHPCompatibility.Constants.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"/>
+		<exclude name="PHPCompatibility.Constants.NewConstants.t_traitFound"/>
 	</rule>
 
 </ruleset>

.travis.yml

@@ -20,6 +20,7 @@ php:
     - 7.0
     - 7.1
     - 7.2
+    - 7.3
     - nightly
 
 env:
@@ -53,6 +54,10 @@ matrix:
   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.

CHANGELOG.md

@@ -8,6 +8,56 @@ This projects adheres to [Semantic Versioning](https://semver.org/) and [Keep a
 
 _No documentation available about unreleased changes as of yet._
 
+## [1.2.0] - 2018-11-12
+
+### Added
+- New `WordPress.PHP.TypeCasts` sniff to the `WordPress-Core` ruleset.
+    This new sniff checks that PHP type casts are:
+    * lowercase;
+    * short form, i.e. `(bool)` not `(boolean)`;
+    * normalized, i.e. `(float)` not `(real)`.
+   Additionally, the new sniff discourages the use of the `(unset)` and `(binary)` type casts.
+- New `WordPress.Utils.I18nTextDomainFixer` sniff which can compehensively replace/add `text-domain`s in a plugin or theme.
+    Important notes:
+    - This sniff is disabled by default and intended as a utility tool.
+    - The sniff will fix the text domains in all I18n function calls as well as in a plugin/theme `Text Domain:` header.
+    - Passing the following properties will activate the sniff:
+        - `old_text_domain`: an array with one or more (old) text domains which need to be replaced;
+        - `new_text_domain`: the correct (new) text domain as a string.
+- The `WordPress.NamingConventions.PrefixAllGlobals` sniff will now also verify that namespace names use a valid prefix.
+    * The sniff allows for underscores and (other) non-word characters in a passed prefix to be converted to namespace separators when used in a namespace name.
+        In other words, if a prefix of `my_plugin` is passed as a value to the `prefixes` property, a namespace name of both `My\Plugin` as well as `My_Plugin\\`, will be accepted automatically.
+    * Passing a prefix property value containing namespace separators will now also be allowed and will no longer trigger a warning.
+- `WordPress` to the prefix blacklist for the `WordPress.NamingConventions.PrefixAllGlobals` sniff.
+    While the prefix cannot be `WordPress`, a prefix can still _start with_ or _contain_ `WordPress`.
+- Additional unit tests covering a change in the tokenizer which will be included in the upcoming `PHP_CodeSniffer` 3.4.0 release.
+- A variety of issue templates for use on GitHub.
+
+### Changed
+- The `Sniff::valid_direct_scope()` method will now return the `$stackPtr` to the valid scope if a valid direct scope has been detected. Previously, it would return `true`.
+- Minor hardening and efficiency improvements to the `WordPress.NamingConventions.PrefixAllGlobals` sniff.
+- The inline documentation of the `WordPress-Core` ruleset has been updated to be in line again with [the handbook](https://make.wordpress.org/core/handbook/best-practices/coding-standards/php/).
+- The inline links to documentation about the VIP requirements have been updated.
+- Updated the [custom ruleset example](https://github.com/WordPress-Coding-Standards/WordPress-Coding-Standards/blob/develop/phpcs.xml.dist.sample) to recommend using `PHPCompatibilityWP` rather than `PHPCompatibility`.
+- All sniffs are now also being tested against PHP 7.3 for consistent sniff results.
+    Note: PHP 7.3 is only supported in combination with PHPCS 3.3.1 or higher as `PHP_CodeSniffer` itself has an incompatibility in earlier versions.
+- Minor grammar fixes in text strings and documentation.
+- Minor consistency improvement for the unit test case files.
+- Minor tweaks to the `composer.json` file.
+- Updated the PHPCompatibility `dev` dependency.
+
+### Removed
+- The `WordPress.WhiteSpace.CastStructureSpacing.NoSpaceAfterCloseParenthesis` error code as an error for the same issue was already being thrown by an included upstream sniff.
+
+### Fixed
+- The `WordPress.CodeAnalysis.EmptyStatement` would throw a false positive for an empty condition in a `for()` statement.
+- The `Sniff::is_class_property()` method could, in certain circumstances, incorrectly recognize parameters in a method declaration as class properties. It would also, incorrectly, fail to recognize class properties when the object they are declared in, was nested in parentheses.
+    This affected, amongst others, the `GlobalVariablesOverride` sniff.
+- The `Sniff::get_declared_namespace_name()` method could get confused over whitespace and comments within a namespace name, which could lead to incorrect results (mostly underreporting).
+    This affected, amongst others, the `GlobalVariablesOverride` sniff.
+    The return value of the method will now no longer contain any whitespace or comments encountered.
+- The `Sniff::has_whitelist_comment()` method would sometimes incorrectly regard `// phpcs:set` comments as whitelist comments.
+
 ## [1.1.0] - 2018-09-10
 
 ### Added
@@ -276,8 +326,8 @@ If you are a maintainer of an external standard based on WPCS and any of your cu
 - The `WordPress.VIP.CronInterval` sniff now allows for customizing the minimum allowed cron interval by [setting a property in a custom ruleset](https://github.com/WordPress-Coding-Standards/WordPress-Coding-Standards/wiki/Customizable-sniff-properties#vip-croninterval-minimum-interval).
 - The `WordPress.VIP.RestrictedFunctions` sniff used to prohibit the use of certain WP native functions, recommending the use of `wpcom_vip_get_term_link()`, `wpcom_vip_get_term_by()` and `wpcom_vip_get_category_by_slug()` instead, as the WP native functions were not being cached. As the results of the relevant WP native functions are cached as of WP 4.8, the advice has now been reversed i.e. use the WP native functions instead of `wpcom...` functions.
 - The `WordPress.VIP.PostsPerPage` sniff now allows for customizing the `post_per_page` limit for which the sniff will trigger by [setting a property in a custom ruleset](https://github.com/WordPress-Coding-Standards/WordPress-Coding-Standards/wiki/Customizable-sniff-properties#vip-postsperpage-post-limit).
-- The `WordPress.WP.I18n` sniff will now allow and actively encourage omitting the text-domain in I18n function calls if the text-domain passed via the `text_domain` property is `default`, i.e. the domain used by Core.
-    When `default` is one of several text-domains passed via the `text_domain` property, the error thrown when the domain is missing has been downgraded to a `warning`.
+- The `WordPress.WP.I18n` sniff will now allow and actively encourage omitting the text domain in I18n function calls if the text domain passed via the `text_domain` property is `default`, i.e. the domain used by Core.
+    When `default` is one of several text domains passed via the `text_domain` property, the error thrown when the domain is missing has been downgraded to a `warning`.
 - The `WordPress.XSS.EscapeOutput` sniff now has a separate error code `OutputNotEscapedShortEcho` and the error message texts have been updated.
 - Moved `Squiz.PHP.Eval` from the `WordPress-Extra` and `WordPress-VIP` to the `WordPress-Core` ruleset.
 - Removed two sniffs from the `WordPress-VIP` ruleset which were already included via the `WordPress-Core` ruleset.
@@ -526,7 +576,7 @@ You are also encouraged to check the file history of any WPCS classes you extend
 ## [0.10.0] - 2016-08-29
 
 ### Added
-- `WordPress.WP.I18n` sniff to the `WordPress-Core` ruleset to flag dynamic translatable strings and textdomains.
+- `WordPress.WP.I18n` sniff to the `WordPress-Core` ruleset to flag dynamic translatable strings and text domains.
 - `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.
@@ -539,7 +589,7 @@ You are also encouraged to check the file history of any WPCS classes you extend
 - 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.
+- Recommendation to also use the [PHPCompatibility](https://github.com/PHPCompatibility/PHPCompatibility) ruleset to the Readme.
 
 ### Changed
 - The minimum required PHP_CodeSniffer version to 2.6.0.
@@ -760,6 +810,7 @@ See the comparison for full list.
 Initial tagged release.
 
 [Unreleased]: https://github.com/WordPress-Coding-Standards/WordPress-Coding-Standards/compare/master...HEAD
+[1.2.0]: https://github.com/WordPress-Coding-Standards/WordPress-Coding-Standards/compare/1.1.0...1.2.0
 [1.1.0]: https://github.com/WordPress-Coding-Standards/WordPress-Coding-Standards/compare/1.0.0...1.1.0
 [1.0.0]: https://github.com/WordPress-Coding-Standards/WordPress-Coding-Standards/compare/0.14.1...1.0.0
 [0.14.1]: https://github.com/WordPress-Coding-Standards/WordPress-Coding-Standards/compare/0.14.0...0.14.1

README.md

@@ -37,6 +37,7 @@
 * [Running your code through WPCS automatically using CI tools](#running-your-code-through-wpcs-automatically-using-ci-tools)
     + [Travis CI](#travis-ci)
 * [Fixing errors or whitelisting them](#fixing-errors-or-whitelisting-them)
+    + [Tools shipped with WPCS](#tools-shipped-with-wpcs)
 * [Contributing](#contributing)
 * [License](#license)
 
@@ -136,7 +137,7 @@ You can use the following as standard names when invoking `phpcs` to select snif
   - `WordPress-Extra` - extended ruleset for recommended best practices, not sufficiently covered in the WordPress core coding standards
     - includes `WordPress-Core`
 
-**Notes:** This WPCS package contains the sniffs for another ruleset, `WordPress-VIP`. This ruleset was originally intended to aid with the [WordPress.com VIP coding requirements](https://vip.wordpress.com/documentation/code-review-what-we-look-for/), but this is no longer used or recommended by the WordPress.com VIP team or their clients, since they prefer to use their [official VIP coding standards](https://github.com/Automattic/VIP-Coding-Standards) ruleset instead.
+**Notes:** This WPCS package contains the sniffs for another ruleset, `WordPress-VIP`. This ruleset was originally intended to aid with the [WordPress.com VIP coding requirements](https://vip.wordpress.com/documentation/vip-go/code-review-blockers-warnings-notices/), but this is no longer used or recommended by the WordPress.com VIP team or their clients, since they prefer to use their [official VIP coding standards](https://github.com/Automattic/VIP-Coding-Standards) ruleset instead.
 
 Before WPCS `1.0.0`, the WordPress-VIP ruleset was included as part of the complete `WordPress` ruleset. **As of `1.0.0` the `WordPress-VIP` ruleset is not part of the WordPress ruleset, and it is deprecated**. The remaining `WordPress-VIP` sniffs may still be referenced in custom rulesets, so to maintain some backwards compatibility, they will remain in WPCS until `2.0.0`. See [#1309](https://github.com/WordPress-Coding-Standards/WordPress-Coding-Standards/issues/1309) for more information.
 
@@ -269,6 +270,21 @@ More examples and advice about integrating PHPCS in your Travis build tests can
 
 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).
 
+### Tools shipped with WPCS
+
+Since version 1.2.0, WPCS has a special sniff category `Utils`.
+
+This sniff category contains some tools which, generally speaking, will only be needed to be run once over a codebase and for which the fixers can be considered _risky_, i.e. very careful review by a developer is needed before accepting the fixes made by these sniffs.
+
+The sniffs in this category are disabled by default and can only be activated by adding some properties for each sniff via a custom ruleset.
+
+At this moment, WPCS offer the following tools:
+* `WordPress.Utils.I18nTextDomainFixer` - This sniff can replace the text domain used in a code-base.
+    The sniff will fix the text domains in both I18n function calls as well as in a plugin/theme header.
+    Passing the following properties will activate the sniff:
+    - `old_text_domain`: an array with one or more (old) text domain names which need to be replaced;
+    - `new_text_domain`: the correct (new) text domain as a string.
+
 
 ## Contributing