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

0.5.0
WordPress · Jun 1, 2015 · 0460804 · 0460804
2 parents 4b7f565 + 3d6a7eb
commit 0460804
Show file tree

Hide file tree

Showing 26 changed files with 2,510 additions and 916 deletions.
diff --git a/.travis.yml b/.travis.yml
@@ -8,19 +8,32 @@ php:
     - 5.4
     - 5.5
     - 5.6
-    - nightly
-    - hhvm
+
+env:
+  - PHPCS_BRANCH=master
+  - PHPCS_BRANCH=2.2.0
 
 matrix:
+  include:
+    # 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
+      env: PHPCS_BRANCH=master
+    - php: nightly
+      env: PHPCS_BRANCH=master
   allow_failures:
+    # Allow failures for unstable builds.
     - php: nightly
     - php: hhvm
+    - env: PHPCS_BRANCH=3.0
 
 before_script:
     - export PHPCS_DIR=/tmp/phpcs
-    - export PHPCS_BRANCH=master
+    - 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_DIR/scripts/phpcs --config-set installed_paths $(pwd)
+    - $PHPCS_BIN --config-set installed_paths $(pwd)
 
 script:
     - find . \( -name '*.php' \) -exec php -lf {} \;

diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -5,10 +5,45 @@ This projects adheres to [Semantic Versioning](http://semver.org/) and [Keep a C
 
 ## [Unreleased]
 
+### Added
+- Sniff to flag dynamic translatable strings and textdomains.
+- `get_children()`, `wp_get_object_terms()`, `wp_get_post_(categories|tags|terms)()`, 
+`get_category_by_slug()`, `get_cat_ID()`, `count_user_posts()`, and `wp_old_slug_redirect()` 
+to the list of restricted functions in the `WordPress.VIP.RestrictedFunctions` sniff.
+
+## [0.5.0] - 2015-06-01
+
 ### Added
 - `WordPress.CSRF.NonceVerification` sniff to flag form processing without nonce verification.
+- `in_array()` and `is_array()` to the list of sanitizing functions.
+- Support for automatic error fixing to the `WordPress.Arrays.ArrayDeclaration` sniff.
+- `WordPress.PHP.StrictComparisions` to the `WordPress-VIP` and `WordPress-Extra` rulesets.
+- `WordPress-Docs` ruleset to sniff for proper commenting.
+- `Generic.PHP.LowerCaseKeyword`, `Generic.Files.EndFileNewline`, `Generic.Files.LowercasedFilename`, 
+`Generic.Formatting.SpaceAfterCast`, and `Generic.Functions.OpeningFunctionBraceKernighanRitchie` to the `WordPress-Core` ruleset.
+- `Generic.PHP.DeprecatedFunctions`, `Generic.PHP.ForbiddenFunctions`, `Generic.Functions.CallTimePassByReference`, 
+`Generic.Formatting.DisallowMultipleStatements`, `Generic.CodeAnalysis.EmptyStatement`, 
+`Generic.CodeAnalysis.ForLoopShouldBeWhileLoop`, `Generic.CodeAnalysis.ForLoopWithTestFunctionCall`, 
+`Generic.CodeAnalysis.JumbledIncrementer`, `Generic.CodeAnalysis.UnconditionalIfStatement`, 
+`Generic.CodeAnalysis.UnnecessaryFinalModifier`, `Generic.CodeAnalysis.UselessOverridingMethod`, 
+`Generic.Classes.DuplicateClassName`, and `Generic.Strings.UnnecessaryStringConcat` to the `WordPress-Extra` ruleset.
+- Error for missing use of `wp_unslash()` on superglobal data to the `WordPress.VIP.ValidatedSanitizedInput` sniff. 
+
+### Changed
+- The `WordPress.VIP.ValidatedSanitizedInput` sniff to require sanitization of input even when it is being directly escaped and output.
+- The minimum required PHP_CodeSniffer version to 2.2.0.
+- The `WordPress.VIP.ValidatedSanitizedInput` and `WordPress.XSS.EscapeOutput` sniffs: 
+the list of escaping functions was split from the list of sanitizing functions. The `customSanitizingFunctions` 
+property has been moved to the `ValidatedSanitizedInput` sniff, and the `customEscapingFunctions`
+property should now be used instead for the `EscapeOutput` sniff.
+- The `WordPress.Arrays.ArrayDeclaration` sniff to give errors for `NoSpaceAfterOpenParenthesis`, `SpaceAfterArrayOpener`, and `SpaceAfterArrayCloser`, instead of warnings.
+- The `WordPress.NamingConventions.ValidFunctionName` sniff to allow camelCase method names in classes that implement interfaces.
+
+### Fixed
+- The `WordPress.VIP.ValidatedSanitizedInput` sniff not reporting missing validation when reporting missing sanitization.
+- The `WordPress.VIP.ValidatedSanitizedInput` sniff flagging superglobals as needing sanitization when they were only being used in a comparison using `if` or `switch`, etc.
 
-## [0.4.0] - 2015-5-1
+## [0.4.0] - 2015-05-01
 
 ### Added
 - Change log file.

diff --git a/README.md b/README.md
@@ -31,7 +31,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 you have the **latest version** of CodeSniffer (earlier versions, e.g. ~1.5.5, may warn about incorrect line indentation on every single line even if your code is actually correct.)
+  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)).
 
 2. Clone WordPress standards repository:
 
@@ -41,6 +41,21 @@ For convenience of using `phpcs` as global command you might want to add path to
 
         phpcs --config-set installed_paths /path/to/wpcs
 
+
+To summarize:
+
+```bash
+cd ~/projects
+git clone https://github.com/squizlabs/PHP_CodeSniffer.git phpcs
+git clone -b master https://github.com/WordPress-Coding-Standards/WordPress-Coding-Standards.git wpcs
+cd phpcs
+./scripts/phpcs --config-set installed_paths ../wpcs
+```
+
+And then add the `~/projects/phpcs/scripts` directory to your `PATH` environment variable via your `.bashrc`.
+
+You should then see `WordPress-Core` et al listed when you run `phpcs -i`.
+
 ## How to use
 
 ### Command line

diff --git a/WordPress-Core/ruleset.xml b/WordPress-Core/ruleset.xml
@@ -38,13 +38,27 @@
 	<rule ref="Squiz.Strings.DoubleQuoteUsage.ContainsVar">
 		<severity>0</severity>
 	</rule>
+
+	<rule ref="Generic.PHP.LowerCaseKeyword"/>
 
 	<rule ref="Generic.Files.LineEndings">
 		<properties>
 			<property name="eolChar" value="\n"/>
 		</properties>
 	</rule>
 
+
+	<rule ref="Generic.Files.EndFileNewline"/>
+
+	<!-- https://make.wordpress.org/core/handbook/coding-standards/php/#naming-conventions -->
+	<rule ref="Generic.Files.LowercasedFilename"/>
+
+	<!-- https://make.wordpress.org/core/handbook/coding-standards/php/#space-usage -->
+	<rule ref="Generic.Formatting.SpaceAfterCast"/>
+
+	<!-- https://make.wordpress.org/core/handbook/coding-standards/php/#brace-style -->
+	<rule ref="Generic.Functions.OpeningFunctionBraceKernighanRitchie"/>
+
 	<rule ref="PEAR.Functions.FunctionCallSignature">
 		<properties>
 			<property name="requiredSpacesAfterOpen" value="1" />
@@ -58,7 +72,9 @@
 		<severity>0</severity>
 	</rule>
 
-	<rule ref="WordPress.Arrays.ArrayDeclaration"/>
+	<rule ref="WordPress.Arrays.ArrayDeclaration">
+		<exclude name="WordPress.Arrays.ArrayDeclaration.SingleLineNotAllowed" />
+	</rule>
 	<rule ref="WordPress.Arrays.ArrayKeySpacingRestrictions"/>
 	<rule ref="WordPress.Classes.ValidClassName"/>
 	<rule ref="WordPress.Files.FileName"/>

diff --git a/WordPress-Docs/ruleset.xml b/WordPress-Docs/ruleset.xml
@@ -0,0 +1,102 @@
+<?xml version="1.0"?>
+<ruleset name="WordPress Docs">
+	<description>WordPress Coding Standards for Inline Documentation and Comments</description>
+
+	<rule ref="Squiz.Commenting">
+		<!-- Excluded to allow /* translators: ... */ comments -->
+		<exclude name="Squiz.Commenting.BlockComment.SingleLine"/>
+		<!-- Sniff seems to require indenting with spaces -->
+		<exclude name="Squiz.Commenting.BlockComment.FirstLineIndent"/>
+		<!-- Sniff seems to require indenting with spaces -->
+		<exclude name="Squiz.Commenting.BlockComment.LineIndent"/>
+		<!-- Sniff seems to require indenting with spaces -->
+		<exclude name="Squiz.Commenting.BlockComment.LastLineIndent"/>
+		<!-- WP requires /** for require() et al. See https://github.com/squizlabs/PHP_CodeSniffer/pull/581 -->
+		<exclude name="Squiz.Commenting.BlockComment.WrongStart"/>
+		<!-- WP handbook doesn't clarify one way or another, so ignore -->
+		<exclude name="Squiz.Commenting.BlockComment.NoEmptyLineAfter"/>
+
+		<!-- WP prefers indicating @since, @package, @subpackage etc in class comments -->
+		<exclude name="Squiz.Commenting.ClassComment.TagNotAllowed"/>
+
+		<!-- WP doesn't require //end ... for classes and functions -->
+		<exclude name="Squiz.Commenting.ClosingDeclarationComment.Missing"/>
+
+		<!-- Excluded to allow param documentation for arrays  -->
+		<exclude name="Squiz.Commenting.DocCommentAlignment.SpaceAfterStar"/>
+
+		<!-- WP doesn't require a @author value for Squiz -->
+		<exclude name="Squiz.Commenting.FileComment.IncorrectAuthor"/>
+		<!-- WP doesn't require a @copyright value for Squiz -->
+		<exclude name="Squiz.Commenting.FileComment.IncorrectCopyright"/>
+		<!-- WP doesn't require @author tags -->
+		<exclude name="Squiz.Commenting.FileComment.MissingAuthorTag"/>
+		<!-- WP doesn't require @subpackage tags -->
+		<exclude name="Squiz.Commenting.FileComment.MissingSubpackageTag"/>
+		<!-- WP doesn't require @copyright tags -->
+		<exclude name="Squiz.Commenting.FileComment.MissingCopyrightTag"/>
+		<!-- WP has a different prefered order of tags -->
+		<exclude name="Squiz.Commenting.FileComment.PackageTagOrder"/>
+		<!-- WP has a different prefered order of tags -->
+		<exclude name="Squiz.Commenting.FileComment.SubpackageTagOrder"/>
+		<!-- WP has a different prefered order of tags -->
+		<exclude name="Squiz.Commenting.FileComment.AuthorTagOrder"/>
+		<!-- WP has a different prefered order of tags -->
+		<exclude name="Squiz.Commenting.FileComment.CopyrightTagOrder"/>
+
+		<!-- WP prefers int and bool instead of integer and boolean -->
+		<exclude name="Squiz.Commenting.FunctionComment.IncorrectParamVarName"/>
+		<!-- WP prefers int and bool instead of integer and boolean -->
+		<exclude name="Squiz.Commenting.FunctionComment.InvalidReturn"/>
+		<!-- WP prefers indicating a @return null for early returns -->
+		<exclude name="Squiz.Commenting.FunctionComment.InvalidReturnNotVoid"/>
+		<!-- WP states not all functions require @return -->
+		<exclude name="Squiz.Commenting.FunctionComment.MissingReturn"/>
+		<!-- Excluded to allow param documentation for arrays  -->
+		<exclude name="Squiz.Commenting.FunctionComment.ParamCommentNotCapital"/>
+		<!-- Excluded to allow param documentation for arrays  -->
+		<exclude name="Squiz.Commenting.FunctionComment.SpacingAfterParamName"/>
+		<!-- WP doesn't require type hints -->
+		<exclude name="Squiz.Commenting.FunctionComment.TypeHintMissing"/>
+
+		<!-- Exclude to allow duplicate hooks to be documented -->
+		<exclude name="Squiz.Commenting.InlineComment.DocBlock"/>
+
+		<!-- Not in Inline Docs standard, and a code smell -->
+		<exclude name="Squiz.Commenting.LongConditionClosingComment"/>
+
+		<!-- Not in Inline Docs standard, and needed to bypass WPCS checks -->
+		<exclude name="Squiz.Commenting.PostStatementComment"/>
+
+		<!-- WP prefers int and bool instead of integer and boolean -->
+		<exclude name="Squiz.Commenting.VariableComment.IncorrectVarType"/>
+		<!-- WP demands a @since tag for class variables -->
+		<exclude name="Squiz.Commenting.VariableComment.TagNotAllowed"/>
+		<!-- WP prefers @since first -->
+		<exclude name="Squiz.Commenting.VariableComment.VarOrder"/>
+	</rule>
+
+	<rule ref="Generic.Commenting">
+		<!-- WP has different alignment of tag values -->
+		<exclude name="Generic.Commenting.DocComment.TagValueIndent"/>
+		<!-- WP has a different prefered order of tags -->
+		<exclude name="Generic.Commenting.DocComment.ParamNotFirst"/>
+		<!-- Excluded to allow param documentation for arrays  -->
+		<exclude name="Generic.Commenting.DocComment.ParamGroup"/>
+		<!-- WP prefers no empty line between @param tags and @return -->
+		<exclude name="Generic.Commenting.DocComment.NonParamGroup"/>
+		<!-- Excluded to allow param documentation for arrays  -->
+		<exclude name="Generic.Commenting.DocComment.TagsNotGrouped"/>
+		<!-- Exclude to allow duplicate hooks to be documented -->
+		<exclude name="Generic.Commenting.DocComment.ContentAfterOpen"/>
+		<!-- Exclude to allow duplicate hooks to be documented -->
+		<exclude name="Generic.Commenting.DocComment.SpacingBeforeShort"/>
+		<!-- Exclude to allow duplicate hooks to be documented -->
+		<exclude name="Generic.Commenting.DocComment.ContentBeforeClose"/>
+
+		<!-- WP allows @todo's in comments -->
+		<exclude name="Generic.Commenting.Todo.CommentFound"/>
+		<!-- WP allows @todo's in comments -->
+		<exclude name="Generic.Commenting.Todo.TaskFound"/>
+	</rule>
+</ruleset>
diff --git a/WordPress-Extra/ruleset.xml b/WordPress-Extra/ruleset.xml
@@ -2,11 +2,35 @@
 <ruleset name="WordPress Extra">
 	<description>Best practices beyond core WordPress Coding Standards</description>
 
+	<rule ref="Generic.PHP.DeprecatedFunctions"/>
+	<rule ref="Generic.PHP.ForbiddenFunctions"/>
+	<rule ref="Generic.Functions.CallTimePassByReference"/>
+	<rule ref="Generic.Formatting.DisallowMultipleStatements"/>
+	<rule ref="Generic.CodeAnalysis.EmptyStatement" />
+	<rule ref="Generic.CodeAnalysis.ForLoopShouldBeWhileLoop"/>
+	<rule ref="Generic.CodeAnalysis.ForLoopWithTestFunctionCall"/>
+	<rule ref="Generic.CodeAnalysis.JumbledIncrementer"/>
+	<rule ref="Generic.CodeAnalysis.UnconditionalIfStatement"/>
+	<rule ref="Generic.CodeAnalysis.UnnecessaryFinalModifier"/>
+	<rule ref="Generic.CodeAnalysis.UselessOverridingMethod"/>
+	<rule ref="Generic.Classes.DuplicateClassName"/>
+	<rule ref="Generic.Strings.UnnecessaryStringConcat"/>
+
+	<!-- This sniff is not refined enough for general use -->
+	<!-- https://github.com/WordPress-Coding-Standards/WordPress-Coding-Standards/pull/382#discussion_r29970107 -->
+	<!--<rule ref="Generic.Formatting.MultipleStatementAlignment"/>-->
+
+	<!-- Hook callbacks may not use all params -->
+	<!-- https://github.com/WordPress-Coding-Standards/WordPress-Coding-Standards/pull/382#discussion_r29981655 -->
+	<!--<rule ref="Generic.CodeAnalysis.UnusedFunctionParameter"/>-->
+
 	<rule ref="WordPress-Core"/>
 
 	<rule ref="WordPress.XSS.EscapeOutput"/>
+	<rule ref="WordPress.CSRF.NonceVerification" />
 	<rule ref="WordPress.PHP.DiscouragedFunctions"/>
 	<rule ref="WordPress.WP.EnqueuedResources"/>
 	<rule ref="WordPress.Variables.GlobalVariables"/>
+	<rule ref="WordPress.PHP.StrictComparisons" />
 
 </ruleset>
diff --git a/WordPress-VIP/ruleset.xml b/WordPress-VIP/ruleset.xml
@@ -11,5 +11,7 @@
 	<rule ref="WordPress.VIP"/>
 
 	<rule ref="WordPress.XSS.EscapeOutput"/>
+	<rule ref="WordPress.CSRF.NonceVerification" />
+	<rule ref="WordPress.PHP.StrictComparisons" />
 
 </ruleset>