Added
- The
WordPress.WP.I18n
sniff contains a new check for translatable text strings which are wrapped in HTML tags, like<h1>Translate me</h1>
. Those tags should be moved out of the translatable string.
Note: Translatable strings wrapped in<a href..>
tags where the URL is intended to be localized will not trigger this check.
Changed
- The default value for
minimum_supported_wp_version
, as used by a number of sniffs detecting usage of deprecated WP features, has been updated to5.1
. - The
WordPress.WP.DeprecatedFunctions
sniff will now detect functions deprecated in WP 5.4. - Improved grammar of an error message in the
WordPress.WP.DiscouragedFunctions
sniff. - CI: The codebase is now - preliminary - being tested against the PHPCS 4.x development branch.
Fixed
- All function call detection sniffs: fixed a bug where constants with the same name as one of the targeted functions could inadvertently be recognized as if they were a called function.
WordPress.DB.PreparedSQL
: fixed a bug where the sniff would trigger on the namespace separator character\\
.WordPress.Security.EscapeOutput
: fixed a bug with the variable replacement in one of the error messages.
Assets
2
Added
- Metrics to the
WordPress.Arrays.CommaAfterArrayItem
sniff. These can be displayed using--report=info
. - The
sanitize_hex_color()
and thesanitize_hex_color_no_hash()
functions to theescapingFunctions
list used by theWordPress.Security.EscapeOutput
sniff.
Changed
- The recommended version of the suggested DealerDirect PHPCS Composer plugin is now
^0.6
.
Fixed
WordPress.PHP.NoSilencedErrors
: depending on the custom properties set, the metrics would be different.WordPress.WhiteSpace.ControlStructureSpacing
: fixed undefined index notice for closures withuse
.WordPress.WP.GlobalVariablesOverride
: fixed undefined offset notice when thetreat_files_as_scoped
property would be set totrue
.WordPress.WP.I18n
: fixed a Trying to access array offset on value of type null error when the sniff was run on PHP 7.4 and would encounter a translation function expecting singular and plural texts for which one of these arguments was missing.
Assets
2
Note: The repository has moved. The new URL is https://github.com/WordPress/WordPress-Coding-Standards.
The move does not affect the package name for Packagist. This remains the same: wp-coding-standards/wpcs
.
Added
- New
WordPress.DateTime.CurrentTimeTimestamp
sniff to theWordPress-Core
ruleset, which checks against the use of the WP nativecurrent_time()
function to retrieve a timestamp as this won't be a real timestamp. Includes an auto-fixer. - New
WordPress.DateTime.RestrictedFunctions
sniff to theWordPress-Core
ruleset, which checks for the use of certain date/time related functions. Initially this sniff forbids the use of the PHP nativedate_default_timezone_set()
anddate()
functions. - New
WordPress.PHP.DisallowShortTernary
sniff to theWordPress-Core
ruleset, which, as the name implies, disallows the use of short ternaries. - New
WordPress.CodeAnalysis.EscapedNotTranslated
sniff to theWordPress-Extra
ruleset which will warn when a text string is escaped for output, but not being translated, while the arguments passed to the function call give the impression that translation is intended. - New
WordPress.NamingConventions.ValidPostTypeSlug
sniff to theWordPress-Extra
ruleset which will examine calls toregister_post_type()
and throw errors when an invalid post type slug is used. Generic.Arrays.DisallowShortArraySyntax
to theWordPress-Core
ruleset.WordPress.NamingConventions.PrefixAllGlobals
: thePHP
prefix has been added to the prefix blacklist as it is reserved by PHP itself.- The
wp_sanitize_redirect()
function to thesanitizingFunctions
list used by theWordPress.Security.NonceVerification
,WordPress.Security.ValidatedSanitizedInput
andWordPress.Security.EscapeOutput
sniffs. - The
sanitize_key()
and thehighlight_string()
functions to theescapingFunctions
list used by theWordPress.Security.EscapeOutput
sniff. - The
RECOVERY_MODE_COOKIE
constant to the list of WP Core constants which may be defined by plugins and themes and therefore don't need to be prefixed (WordPress.NamingConventions.PrefixAllGlobals
). $content_width
,$plugin
,$mu_plugin
and$network_plugin
to the list of WP globals which is used by both theWordPress.Variables.GlobalVariables
and theWordPress.NamingConventions.PrefixAllGlobals
sniffs.Sniff::is_short_list()
utility method to determine whether a short array open/close token actually represents a PHP 7.1+ short list.Sniff::find_list_open_close()
utility method to find the opener and closer forlist()
constructs, including short lists.Sniff::get_list_variables()
utility method which will retrieve an array with the token pointers to the variables which are being assigned to in alist()
construct. Includes support for short lists.Sniff::is_function_deprecated()
static utility method to determine whether a declared function has been marked as deprecated in the function DocBlock.- End-user documentation to the following existing sniffs:
WordPress.Arrays.ArrayIndentation
,WordPress.Arrays.ArrayKeySpacingRestrictions
,WordPress.Arrays.MultipleStatementAlignment
,WordPress.Classes.ClassInstantiation
,WordPress.NamingConventions.ValidHookName
,WordPress.PHP.IniSet
,WordPress.Security.SafeRedirect
,WordPress.WhiteSpace.CastStructureSpacing
,WordPress.WhiteSpace.DisallowInlineTabs
,WordPress.WhiteSpace.PrecisionAlignment
,WordPress.WP.CronInterval
,WordPress.WP.DeprecatedClasses
,WordPress.WP.DeprecatedFunctions
,WordPress.WP.DeprecatedParameters
,WordPress.WP.DeprecatedParameterValues
,WordPress.WP.EnqueuedResources
,WordPress.WP.PostsPerPage
.
This documentation can be exposed via thePHP_CodeSniffer
--generator=...
command-line argument.
Changed
- The default value for
minimum_supported_wp_version
, as used by a number of sniffs detecting usage of deprecated WP features, has been updated to5.0
. - The
WordPress.Arrays.ArrayKeySpacingRestrictions
sniff has two new error codes:TooMuchSpaceBeforeKey
andTooMuchSpaceAfterKey
. Both auto-fixable.
The sniff will now check that there is exactly one space on the inside of the square brackets around the array key for non-string, non-numeric array keys. Previously, it only checked that there was whitespace, not how much whitespace. WordPress.Arrays.ArrayKeySpacingRestrictions
: the fixers have been made more efficient and less fixer-conflict prone.WordPress.NamingConventions.PrefixAllGlobals
: plugin/theme prefixes should be at least three characters long. A newShortPrefixPassed
error has been added for when the prefix passed does not comply with this rule.WordPress.WhiteSpace.CastStructureSpacing
now allows for no whitespace before a cast when the cast is preceded by the spread...
operator. This pre-empts a fixer conflict for when the spacing around the spread operator will start to get checked.- The
WordPress.WP.DeprecatedClasses
sniff will now detect classes deprecated in WP 4.9 and WP 5.3. - The
WordPress.WP.DeprecatedFunctions
sniff will now detect functions deprecated in WP 5.3. WordPress.NamingConventions.ValidHookName
now has "cleaner" error messages and higher precision for the line on which an error is thrown.WordPress.Security.EscapeOutput
: if an error refers to array access via a variable, the array index key will now be included in the error message.- The processing of the
WordPress
ruleset byPHP_CodeSniffer
will now be faster. - Various minor code tweaks and clean up.
- Various minor documentation fixes.
- Documentation: updated the repo URL in all relevant places.
Deprecated
- The
WordPress.WP.TimezoneChange
sniff. Use theWordPress.DateTime.RestrictedFunctions
instead.
The deprecated sniff will be removed in WPCS 3.0.0.
Fixed
- All sniffs in the
WordPress.Arrays
category will no longer treat short lists as if they were a short array. - The
WordPress.NamingConventions.ValidFunctionName
and theWordPress.NamingConventions.PrefixAllGlobals
sniff will now ignore functions marked as@deprecated
. - Both the
WordPress.NamingConventions.PrefixAllGlobals
sniff as well as theWordPress.WP.GlobalVariablesOverride
sniff have been updated to recognize variables being declared via (long/short)list()
constructs and handle them correctly. - Both the
WordPress.NamingConventions.PrefixAllGlobals
sniff as well as theWordPress.WP.GlobalVariablesOverride
sniff will now take a limited list of WP global variables which are intended to be overwritten by plugins/themes into account.
Initially this list contains the$content_width
and the$wp_cockneyreplace
variables. WordPress.NamingConventions.ValidHookName
: will no longer examine a string array access index key as if it were a part of the hook name.WordPress.Security.EscapeOutput
: will no longer trigger on the typicalbasename( __FILE__ )
pattern if found as the first parameter passed to a call to_deprecated_file()
.WordPress.WP.CapitalPDangit
: now allows for the.test
TLD in URLs.- WPCS is now fully compatible with PHP 7.4.
Note:PHP_CodeSniffer
itself is only compatible with PHP 7.4 from PHPCS 3.5.0 onwards.
Assets
2
Changed
- The
WordPress.WP.CapitalPDangit
will now ignore misspelled instances ofWordPress
within constant declarations.
This covers both constants declared usingdefined()
as well as constants declared using theconst
keyword. - The default value for
minimum_supported_wp_version
, as used by a number of sniffs detecting usage of deprecated WP features, has been updated to4.9
.
Removed
paginate_comments_links()
from the list of auto-escaped functionsSniff::$autoEscapedFunctions
.
This affects theWordPress.Security.EscapeOutput
sniff.
Fixed
- The
$current_blog
and$tag_ID
variables have been added to the list of WordPress global variables.
This fixes some false positives from theWordPress.NamingConventions.PrefixAllGlobals
and theWordPress.WP.GlobalVariablesOverride
sniffs. - The generic
TestCase
class name has been added to the$test_class_whitelist
.
This fixes some false positives from theWordPress.NamingConventions.FileName
,WordPress.NamingConventions.PrefixAllGlobals
and theWordPress.WP.GlobalVariablesOverride
sniffs. - The
WordPress.NamingConventions.ValidVariableName
sniff will now correctly recognize$tag_ID
as a WordPress native, mixed-case variable. - The
WordPress.Security.NonceVerification
sniff will now correctly recognize nonce verification within a nested closure or anonymous class.
Assets
2
Added
- New
WordPress.PHP.IniSet
sniff to theWordPress-Extra
ruleset.
This sniff will detect calls toini_set()
andini_alter()
and warn against their use as changing configuration values at runtime leads to an unpredictable runtime environment, which can result in conflicts between core/plugins/themes.- The sniff will not throw notices about a very limited set of "safe" ini directives.
- For a number of ini directives for which there are alternative, non-conflicting ways to achieve the same available, the sniff will throw an
error
and advise using the alternative.
doubleval()
,count()
andsizeof()
toSniff::$unslashingSanitizingFunctions
property.
Whilecount()
and its aliassizeof()
, don't actually unslash or sanitize, the output of these functions is safe to use without unslashing or sanitizing.
This affects theWordPress.Security.ValidatedSanitizedInput
and theWordPress.Security.NonceVerification
sniffs.- The new WP 5.1
WP_UnitTestCase_Base
class to theSniff::$test_class_whitelist
property. - New
Sniff::get_array_access_keys()
utility method to retrieve all array keys for a variable using multi-level array access. - New
Sniff::is_class_object_call()
,Sniff::is_token_namespaced()
utility methods.
These should help make the checking of whether or not a function call is a global function, method call or a namespaced function call more consistent.
This also implements allowing for the namespace keyword being used as an operator. - New
Sniff::is_in_function_call()
utility method to facilitate checking whether a token is (part of) a parameter passed to a specific (set of) function(s). - New
Sniff::is_in_type_test()
utility method to determine if a variable is being type tested, along with aSniff::$typeTestFunctions
property containing the names of the functions this applies to. - New
Sniff::is_in_array_comparison()
utility method to determine if a variable is (part of) a parameter in an array-value comparison, along with aSniff::$arrayCompareFunctions
property containing the names of the relevant functions. - New
Sniff::$arrayWalkingFunctions
property containing the names of array functions which apply a callback to the array, but don't change the array by reference. - New
Sniff::$unslashingFunctions
property containing the names of functions which unslash data passed to them and return the unslashed result.
Changed
- Moved the
WordPress.PHP.StrictComparisons
,WordPress.PHP.StrictInArray
and theWordPress.CodeAnalysis.AssignmentInCondition
sniff from theWordPress-Extra
to theWordPress-Core
ruleset. - The
Squiz.Commenting.InlineComment.SpacingAfter
error is no longer included in theWordPress-Docs
ruleset. - The default value for
minimum_supported_wp_version
, as used by a number of sniffs detecting usage of deprecated WP features, has been updated to4.8
. - The
WordPress.WP.DeprecatedFunctions
sniff will now detect functions deprecated in WP 5.1. - The
WordPress.Security.NonceVerification
sniff now allows for variable type testing, comparisons, unslashing and sanitization before the nonce check. A nonce check within the same scope, however, is still required. - The
WordPress.Security.ValidatedSanitizedInput
sniff now allows for using a superglobal in an array-value comparison without sanitization, same as when the superglobal is used in a scalar value comparison. WordPress.NamingConventions.PrefixAllGlobals
: some of the error messages have been made more explicit.- The error messages for the
WordPress.Security.ValidatedSanitizedInput
sniff will now contain information on the index keys accessed. - The error message for the
WordPress.Security.ValidatedSanitizedInput.InputNotValidated
has been reworded to make it more obvious what the actual issue being reported is. - The error message for the
WordPress.Security.ValidatedSanitizedInput.MissingUnslash
has been reworded. - The
Sniff::is_comparison()
method now has a new$include_coalesce
parameter to allow for toggling whether the null coalesce operator should be seen as a comparison operator. Defaults totrue
. - All sniffs are now also being tested against PHP 7.4 (unstable) for consistent sniff results.
- The recommended version of the suggested DealerDirect PHPCS Composer plugin is now
^0.5.0
. - Various minor code tweaks and clean up.
Removed
ini_set
andini_alter
from the list of functions detected by theWordPress.PHP.DiscouragedFunctions
sniff.
These are now covered via the newWordPress.PHP.IniSet
sniff.in_array()
andarray_key_exists()
from the list ofSniff::$sanitizingFunctions
. These are now handled differently.
Fixed
- The
WordPress.NamingConventions.PrefixAllGlobals
sniff would underreport when global functions would be autoloaded via a Composer autoloadfiles
configuration. - The
WordPress.Security.EscapeOutput
sniff will now recognizemap_deep()
for escaping the values in an array via a callback to an output escaping function. This should prevent false positives. - The
WordPress.Security.NonceVerification
sniff will no longer inadvertently allow for a variable to be sanitized without a nonce check within the same scope. - The
WordPress.Security.ValidatedSanitizedInput
sniff will no longer throw errors when a variable is only being type tested. - The
WordPress.Security.ValidatedSanitizedInput
sniff will now correctly recognize the null coalesce (PHP 7.0) and null coalesce equal (PHP 7.4) operators and will now throw errors for missing unslashing and sanitization where relevant. - The
WordPress.WP.AlternativeFunctions
sniff will no longer recommend using the WP_FileSystem when PHP native input streams, likephp://input
, or the PHP input stream constants are being read or written to. - The
WordPress.WP.AlternativeFunctions
sniff will no longer report on usage of thecurl_version()
function. - The
WordPress.WP.CronInterval
sniff now has improved function recognition which should lower the chance of false positives. - The
WordPress.WP.EnqueuedResources
sniff will no longer throw false positives for inline jQuery code trying to access a stylesheet link tag. - Various bugfixes for the
Sniff::has_nonce_check()
method:- The method will no longer incorrectly identify methods/namespaced functions mirroring the name of WP native nonce verification functions as if they were the global functions.
This will prevent some false negatives. - The method will now skip over nested closed scopes, such as closures and anonymous classes. This should prevent some false negatives for nonce verification being done while not in the correct scope.
These fixes affect theWordPress.Security.NonceVerification
sniff.
- The method will no longer incorrectly identify methods/namespaced functions mirroring the name of WP native nonce verification functions as if they were the global functions.
- The
Sniff::is_in_isset_or_empty()
method now also checks for usage ofarray_key_exist()
andkey_exists()
and will regard these as correct ways to validate a variable.
This should prevent false positives for theWordPress.Security.ValidatedSanitizedInput
and theWordPress.Security.NonceVerification
sniffs. - Various bugfixes for the
Sniff::is_sanitized()
method:- The method presumed the WordPress coding style regarding code layout, which could lead to false positives.
- The method will no longer incorrectly identify methods/namespaced functions mirroring the name of WP/PHP native unslashing/sanitization functions as if they were the global functions.
This will prevent some false negatives. - The method will now recognize
map_deep()
for sanitizing an array via a callback to a sanitization function. This should prevent false positives. - The method will now recognize
stripslashes_deep()
andstripslashes_from_strings_only()
as valid unslashing functions. This should prevent false positives.
All these fixes affect both theWordPress.Security.ValidatedSanitizedInput
and theWordPress.Security.NonceVerification
sniff.
- Various bugfixes for the
Sniff::is_validated()
method:- The method did not verify correctly whether a variable being validated was the same variable as later used which could lead to false negatives.
- The method did not verify correctly whether a variable being validated had the same array index keys as the variable as later used which could lead to both false negatives as well as false positives.
- The method now also checks for usage of
array_key_exist()
andkey_exists()
and will regard these as correct ways to validate a variable. This should prevent some false positives. - The methods will now recognize the null coalesce and the null coalesce equal operators as ways to validate a variable. This prevents some false positives.
The results from theWordPress.Security.ValidatedSanitizedInput
sniff should be more accurate because of these fixes.
- A potential "Undefined index" notice from the
Sniff::is_assignment()
method.
Assets
2
Important information about this release:
WordPressCS 2.0.0 contains breaking changes, both for people using custom rulesets as well as for sniff developers who maintain a custom PHPCS standard based on WordPressCS.
Support for PHP_CodeSniffer
2.x has been dropped, the new minimum PHP_CodeSniffer
version is 3.3.1.
Also, all previously deprecated sniffs, properties and methods have been removed.
Please read the complete changelog carefully before you upgrade.
If you are a maintainer of an external standard based on WordPressCS and any of your custom sniffs are based on or extend WPCS sniffs, please read the Developers Upgrade Guide to WordPressCS 2.0.0.
Changes since 2.0.0-RC1
Fixed
WordPress-Extra
: Reverted back to including theSquiz.WhiteSpace.LanguageConstructSpacing
sniff instead of the newGeneric.WhiteSpace.LanguageConstructSpacing
sniff as the new sniff is not (yet) available when the PEAR install of PHPCS is used.
Changes since 1.2.1
For a full list of changes from the 1.2.1 version, please review the following changelog:
Assets
2
jrfnl
released this
Important information about this release:
This is the first release candidate for WordPressCS 2.0.0.
WordPressCS 2.0.0 contains breaking changes, both for people using custom rulesets as well as for sniff developers who maintain a custom PHPCS standard based on WordPressCS.
Support for PHP_CodeSniffer
2.x has been dropped, the new minimum PHP_CodeSniffer
version is 3.3.1.
Also, all previously deprecated sniffs, properties and methods have been removed.
Please read the complete changelog carefully before you upgrade.
If you are a maintainer of an external standard based on WordPressCS and any of your custom sniffs are based on or extend WPCS sniffs, please read the Developers Upgrade Guide to WordPressCS 2.0.0.
Added
Generic.PHP.DiscourageGoto
,Generic.PHP.LowerCaseType
,Generic.WhiteSpace.ArbitraryParenthesesSpacing
andPSR12.Keywords.ShortFormTypeKeywords
to theWordPress-Core
ruleset.- Checking the spacing around the
instanceof
operator to theWordPress.WhiteSpace.OperatorSpacing
sniff.
Changed
- The minimum required
PHP_CodeSniffer
version to 3.3.1 (was 2.9.0). - The namespace used by WordPressCS has been changed from
WordPress
toWordPressCS\WordPress
.
This was not possible whilePHP_CodeSniffer
2.x was still supported, but WordPressCS, as a good Open Source citizen, does not want to occupy theWordPress
namespace and is releasing its use of it now this is viable. - The
WordPress.DB.PreparedSQL
sniff used the same error code for two different errors.
TheNotPrepared
error code remains, however an additionalInterpolatedNotPrepared
error code has been added for the second error.
If you are referencing the old error code in a ruleset XML file or in inline annotations, you may need to update it. - The
WordPress.NamingConventions.PrefixAllGlobals
sniff used the same error code for some errors as well as warnings.
TheNonPrefixedConstantFound
error code remains for the related error, but the warning will now use the newVariableConstantNameFound
error code.
TheNonPrefixedHooknameFound
error code remains for the related error, but the warning will now use the newDynamicHooknameFound
error code.
If you are referencing the old error codes in a ruleset XML file or in inline annotations, you may need to update these to use the new codes instead. WordPress.NamingConventions.ValidVariableName
: the error messages and error codes used by this sniff have been changed for improved usability and consistency.- The error messages will now show a suggestion for a valid alternative name for the variable.
- The
NotSnakeCaseMemberVar
error code has been renamed toUsedPropertyNotSnakeCase
. - The
NotSnakeCase
error code has been renamed toVariableNotSnakeCase
. - The
MemberNotSnakeCase
error code has been renamed toPropertyNotSnakeCase
. - The
StringNotSnakeCase
error code has been renamed toInterpolatedVariableNotSnakeCase
.
If you are referencing the old error codes in a ruleset XML file or in inline annotations, you may need to update these to use the new codes instead.
- The
WordPress.Security.NonceVerification
sniff used the same error code for both an error as well as a warning.
The old error codeNoNonceVerification
is no longer used.
Theerror
now uses theMissing
error code, while thewarning
now uses theRecommended
error code.
If you are referencing the old error code in a ruleset XML file or in inline annotations, please update these to use the new codes instead. - The
WordPress.WP.DiscouragedConstants
sniff used to have two error codesUsageFound
andDeclarationFound
.
These error codes will now be prefixed by the name of the constant found to allow for more fine-grained excluding/ignoring of warnings generated by this sniff.
If you are referencing the old error codes in a ruleset XML file or in inline annotations, you may need to update these to use the new codes instead. - The
WordPress.WP.GlobalVariablesOverride.OverrideProhibited
error code has been replaced by theWordPress.WP.GlobalVariablesOverride.Prohibited
error code.
If you are referencing the old error code in a ruleset XML file or in inline annotations, you may need to update it. WordPress-Extra
: Replaced the inclusion of theGeneric.Files.OneClassPerFile
,Generic.Files.OneInterfacePerFile
and theGeneric.Files.OneTraitPerFile
sniffs with the newGeneric.Files.OneObjectStructurePerFile
sniff.WordPress-Extra
: Replaced the inclusion of theSquiz.WhiteSpace.LanguageConstructSpacing
sniff with the newGeneric.WhiteSpace.LanguageConstructSpacing
sniff.WordPress-Extra
: Replaced the inclusion of theSquiz.Scope.MemberVarScope
sniff with the more comprehensivePSR2.Classes.PropertyDeclaration
sniff.WordPress.NamingConventions.ValidFunctionName
: Added a unit test confirming support for interfaces extending multiple interfaces.WordPress.NamingConventions.ValidVariableName
: Added unit tests confirming support for multi-variable/property declarations.- The
get_name_suggestion()
method has been moved from theWordPress.NamingConventions.ValidFunctionName
sniff to the baseSniff
class, renamed toget_snake_case_name_suggestion()
and made static. - The rulesets are now validated against the
PHP_CodeSniffer
XSD schema. - Updated the custom ruleset example to use the recommended ruleset syntax for
PHP_CodeSniffer
3.3.1+, including using the new array property format which is now supported. - Dev: The command to run the unit tests has changed. Please see the updated instructions in the CONTRIBUTING.md file.
Thebin/pre-commit
example git hook has been updated to match. Additionally arun-tests
script has been added to thecomposer.json
file for your convenience.
To facilitate this, PHPUnit has been added torequire-dev
, even though it is strictly speaking a dependency of PHPCS, not of WPCS. - Dev: The DealerDirect PHPCS Composer plugin has been added to
require-dev
. - Various code tweaks and clean up.
- User facing documentation, including the wiki, as well as inline documentation has been updated for all the changes contained in WordPressCS 2.0 and other recommended best practices for
PHP_CodeSniffer
3.3.1+.
Deprecated
- The use of the WordPressCS native whitelist comments, which were introduced in WPCS 0.4.0, have been deprecated and support will be removed in WPCS 3.0.0.
The WordPressCS native whitelist comments will continue to work for now, but a deprecation warning will be thrown when they are encountered.
You are encouraged to upgrade our whitelist comment to use the PHPCS native selective ignore annotations as introduced inPHP_CodeSniffer
3.2.0, as soon as possible.
Removed
- Support for PHP 5.3. PHP 5.4 is the minimum requirement for
PHP_CodeSniffer
3.x.
Includes removing any and all workarounds which were in place to still support PHP 5.3. - Support for
PHP_CodeSniffer
< 3.3.1.
Includes removing any and all workarounds which were in place for supporting olderPHP_CodeSniffer
versions. - The
WordPress-VIP
standard which was deprecated since WordPressCS 1.0.0.
For checking a theme/plugin for hosting on the WordPress.com VIP platform, please use the Automattic VIP coding standards instead. - Support for array properties set in a custom ruleset without the
type="array"
attribute.
Support for this was deprecated in WPCS 1.0.0.
If in doubt about how properties should be set in your custom ruleset, please refer to the Customizable sniff properties wiki page which contains XML code examples for setting each and every WPCS native sniff property.
As the minimumPHP_CodeSniffer
version is now 3.3.1, you can now also use the new format for setting array properties, so this would be a great moment to review and update your custom ruleset.
Note: the ability to set select properties from the command-line as comma-delimited strings is not affected by this change. - The following sniffs have been removed outright without deprecation.
If you are referencing these sniffs in a ruleset XML file or in inline annotations, please update these to reference the replacement sniffs instead.WordPress.Functions.FunctionCallSignatureNoParams
- superseded by a bug fix in the upstreamPEAR.Functions.FunctionCallSignature
sniff.WordPress.PHP.DiscourageGoto
- replaced by the same sniff which is now available upstream:Generic.PHP.DiscourageGoto
.WordPress.WhiteSpace.SemicolonSpacing
- superseded by a bug fix in the upstreamSquiz.WhiteSpace.SemicolonSpacing
sniff.WordPress.WhiteSpace.ArbitraryParenthesesSpacing
- replaced by the same sniff which is now available upstream:Generic.WhiteSpace.ArbitraryParenthesesSpacing
.
- The following "base" sniffs which were previously already deprecated and turned into abstract base classes, have been removed:
WordPress.Arrays.ArrayAssignmentRestrictions
- use theAbstractArrayAssignmentRestrictionsSniff
class instead.WordPress.Functions.FunctionRestrictions
- use theAbstractFunctionRestrictionsSniff
class instead.WordPress.Variables.VariableRestrictions
without replacement.
- The following sniffs which were previously deprecated, have been removed:
WordPress.Arrays.ArrayDeclaration
- use the other sniffs in theWordPress.Arrays
category instead.WordPress.CSRF.NonceVerification
- useWordPress.Security.NonceVerification
instead.WordPress.Functions.DontExtract
- useWordPress.PHP.DontExtract
instead.WordPress.Variables.GlobalVariables
- useWordPress.WP.GlobalVariablesOverride
instead.WordPress.VIP.CronInterval
- useWordPress.WP.CronInterval
instead.WordPress.VIP.DirectDatabaseQuery
- useWordPress.DB.DirectDatabaseQuery
instead.WordPress.VIP.PluginMenuSlug
- useWordPress.Security.PluginMenuSlug
instead.WordPress.VIP.SlowDBQuery
- useWordPress.DB.SlowDBQuery
instead.WordPress.VIP.TimezoneChange
- useWordPress.WP.TimezoneChange
instead.WordPress.VIP.ValidatedSanitizedInput
- useWordPress.Security.ValidatedSanitizedInput
instead.WordPress.WP.PreparedSQL
- useWordPress.DB.PreparedSQL
instead.WordPress.XSS.EscapeOutput
- useWordPress.Security.EscapeOutput
instead.WordPress.PHP.DiscouragedFunctions
without direct replacement.
The checks previously contained in this sniff were moved to separate sniffs in WPCS 0.11.0.WordPress.Variables.VariableRestrictions
without replacement.WordPress.VIP.AdminBarRemoval
without replacement.WordPress.VIP.FileSystemWritesDisallow
without replacement.WordPress.VIP.OrderByRand
without replacement.WordPress.VIP.PostsPerPage
without replacement.
Part of the previous functionality was split off in WPCS 1.0.0 to theWordPress.WP.PostsPerPage
sniff.WordPress.VIP.RestrictedFunctions
without replacement.WordPress.VIP.RestrictedVariables
without replacement.WordPress.VIP.SessionFunctionsUsage
without replacement.WordPress.VIP.SessionVariableUsage
without replacement.WordPress.VIP.SuperGlobalInputUsage
without replacement.
- The
WordPress.DB.SlowDBQuery.DeprecatedWhitelistFlagFound
error code which is superseded by the blanket deprecation warning for using the now deprecated WPCS native whitelist comments. - The
WordPress.PHP.TypeCasts.NonLowercaseFound
error code which has been replaced by the upstreamGeneric.PHP.LowerCaseType
sniff. - The
WordPress.PHP.TypeCasts.LongBoolFound
andWordPress.PHP.TypeCasts.LongIntFound
error codes which has been replaced by the new upstreamPSR12.Keywords.ShortFormTypeKeywords
sniff. - The
WordPress.Security.EscapeOutput.OutputNotEscapedShortEcho
error code which was only ever used if WPCS was run on PHP 5.3 with theshort_open_tag
ini directive set tooff
. - The following sniff categories which were previously deprecated, have been removed, though select categories may be reinstated in the future:
CSRF
Functions
Variables
VIP
XSS
WordPress.NamingConventions.ValidVariableName
: ThecustomVariableWhitelist
property, which had been deprecated since WordPressCS 0.11.0. Use thecustomPropertiesWhitelist
property instead.WordPress.Security.EscapeOutput
: ThecustomSanitizingFunctions
property, which had been deprecated since WordPressCS 0.5.0. Use thecustomEscapingFunctions
property instead.WordPress.Security.NonceVerification
: TheerrorForSuperGlobals
andwarnForSuperGlobals
properties, which had been deprecated since WordPressCS 0.12.0.- The
vip_powered_wpcom
function from theSniff::$autoEscapedFunctions
list which is used by theWordPress.Security.EscapeOutput
sniff. - The
AbstractVariableRestrictionsSniff
class, which was deprecated since WordPressCS 1.0.0. - The
Sniff::has_html_open_tag()
utility method, which was deprecated since WordPressCS 1.0.0. - The internal
$php_reserved_vars
property from theWordPress.NamingConventions.ValidVariableName
sniff in favour of using a PHPCS native property which is now available. - The class aliases and WPCS native autoloader used for PHPCS cross-version support.
- The unit test framework workarounds for PHPCS cross-version unit testing.
- Support for the
@codingStandardsChangeSetting
annotation, which is generally only used in unit tests. - The old generic GitHub issue template which was replaced by more specific issue templates in WPCS 1.2.0.
Fixed
- Support for PHP 7.3.
PHP_CodeSniffer
< 3.3.1 was not fully compatible with PHP 7.3. Now the minimum required PHPCS has been upped toPHP_CodeSniffer
3.3.1, WordPressCS will run on PHP 7.3 without issue. WordPress.Arrays.ArrayDeclarationSpacing
: improved fixing of the placement of array items following an array item with a trailing multi-line comment.WordPress.NamingConventions.ValidFunctionName
: the sniff will no longer throw false positives nor duplicate errors for methods declared in nested anonymous classes.
The error message has also been improved for methods in anonymous classes.WordPress.NamingConventions.ValidFunctionName
: the sniff will no longer throw false positives for PHP 4-style class constructors/destructors where the name of the constructor/destructor method did not use the same case as the class name.
Assets
2
Note: This will be the last release supporting PHP_CodeSniffer 2.x.
Changed
- The default value for
minimum_supported_wp_version
, as used by a number of sniffs detecting usage of deprecated WP features, has been updated to4.7
. - The
WordPress.NamingConventions.PrefixAllGlobals
sniff will now report the error for hook names and constant names declared withdefine()
on the line containing the parameter for the hook/constant name. Previously, it would report the error on the line containing the function call. - Various minor housekeeping fixes to inline documentation, rulesets, code.
Removed
comment_author_email_link()
,comment_author_email()
,comment_author_IP()
,comment_author_link()
,comment_author_rss()
,comment_author_url_link()
,comment_author_url()
,comment_author()
,comment_date()
,comment_excerpt()
,comment_form_title()
,comment_form()
,comment_id_fields()
,comment_ID()
,comment_reply_link()
,comment_text_rss()
,comment_text()
,comment_time()
,comment_type()
,comments_link()
,comments_number()
,comments_popup_link()
,comments_popup_script()
,comments_rss_link()
,delete_get_calendar_cache()
,edit_bookmark_link()
,edit_comment_link()
,edit_post_link()
,edit_tag_link()
,get_footer()
,get_header()
,get_sidebar()
,get_the_title()
,next_comments_link()
,next_image_link()
,next_post_link()
,next_posts_link()
,permalink_anchor()
,posts_nav_link()
,previous_comments_link()
,previous_image_link()
,previous_post_link()
,previous_posts_link()
,sticky_class()
,the_attachment_link()
,the_author_link()
,the_author_meta()
,the_author_posts_link()
,the_author_posts()
,the_category_rss()
,the_category()
,the_content_rss()
,the_content()
,the_date_xml()
,the_excerpt_rss()
,the_excerpt()
,the_feed_link()
,the_ID()
,the_meta()
,the_modified_author()
,the_modified_date()
,the_modified_time()
,the_permalink()
,the_post_thumbnail()
,the_search_query()
,the_shortlink()
,the_tags()
,the_taxonomies()
,the_terms()
,the_time()
,the_title_rss()
,the_title()
,wp_enqueue_script()
,wp_meta()
,wp_shortlink_header()
andwp_shortlink_wp_head()
from the list of auto-escaped functionsSniff::$autoEscapedFunctions
. This affects theWordPress.Security.EscapeOutput
sniff.
Fixed
- The
WordPress.WhiteSpace.PrecisionAlignment
sniff would loose the value of a custom setignoreAlignmentTokens
property when scanning more than one file.
Assets
2
Added
- New
WordPress.PHP.TypeCasts
sniff to theWordPress-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/addtext-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 ofmy_plugin
is passed as a value to theprefixes
property, a namespace name of bothMy\Plugin
as well asMy_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.
- 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.
WordPress
to the prefix blacklist for theWordPress.NamingConventions.PrefixAllGlobals
sniff.
While the prefix cannot beWordPress
, a prefix can still start with or containWordPress
.- 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 returntrue
. - 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. - The inline links to documentation about the VIP requirements have been updated.
- Updated the custom ruleset example to recommend using
PHPCompatibilityWP
rather thanPHPCompatibility
. - 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 asPHP_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 afor()
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, theGlobalVariablesOverride
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, theGlobalVariablesOverride
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.
Assets
2
Added
- New
WordPress.PHP.NoSilencedErrors
sniff. This sniff replaces theGeneric.PHP.NoSilencedErrors
sniff which was previously used and included in theWordPress-Core
ruleset.
The WordPress specific version of the sniff differs from the PHPCS version in that it:- Allows the error control operator
@
if it preceeds a function call to a limited list of PHP functions for which no amount of error checking can prevent a PHP warning from being thrown. - Allows for a used-defined list of (additional) function names to be passed to the sniff via the
custom_whitelist
property in a custom ruleset, for which - if the error control operator is detected in front of a function call to one of the functions in this whitelist - no warnings will be thrown. - Displays a brief snippet of code in the
warning
message text to show the context in which the error control operator is being used. The length of the snippet (in tokens) can be customized via thecontext_length
property. - Contains a public
use_default_whitelist
property which can be set from a custom ruleset which regulates whether or not the standard whitelist of PHP functions should be used by the sniff.
The user-defined whitelist will always be respected.
By default, this property is set totrue
for theWordPress-Core
ruleset and tofalse
for theWordPress-Extra
ruleset (which is stricter regarding these kind of best practices).
- Allows the error control operator
- Metrics to the
WordPress.NamingConventions.PrefixAllGlobals
sniff to aid people in determining the most commonly used prefix in a legacy project.
For an example of how to use this feature, please see the detailed explanation in the pull request.
Changed
- The
PEAR.Functions.FunctionCallSignature
sniff, which is part of theWordPress-Core
ruleset, used to allow multiple function call parameters per line in multi-line function calls. This will no longer be allowed.
As of this release, if a function call is multi-line, each parameter should start on a new line and anerror
will be thrown if the code being analysed does not comply with that rule.
The sniff behaviour for single-line function calls is not affected by this change. - Moved the
WordPress.CodeAnalysis.EmptyStatement
sniff from theWordPress-Extra
to theWordPress-Core
ruleset. - Moved the
Squiz.PHP.CommentedOutCode
sniff from theWordPress-Docs
to theWordPress-Extra
ruleset and lowered the threshold for determining whether or not a comment is commented out code from 45% to 40%. - The
WordPress.NamingConventions.PrefixAllGlobals
sniff now has improved support for recognizing whether or not (non-prefixed) globals are declared in the context of unit tests. - The
is_foreach_as()
method has been moved from theGlobalVariablesOverrideSniff
class to the WordPressSniff
base class. - The
Sniff::is_token_in_test_method()
utility method now has improved support for recognizing test methods in anonymous classes. - Minor efficiency improvement to the
Sniff::is_safe_casted()
method. - CI: Minor tweaks to the Travis script.
- CI: Improved Composer scripts for use by WPCS developers.
- Dev: Removed IDE specific files from
.gitignore
. - Readme: Improved the documentation about the project history and the badge display.
Fixed
- The
WordPress.Security.ValidatedSanitizedInput
sniff will now recognize array keys in superglobals independently of the string quote-style used for the array key. - The
WordPress.WhiteSpace.PrecisionAlignment
sniff will no longer throw false positives for DocBlocks for JavaScript functions within inline HTML. WordPress.WP.DeprecatedClasses
: The error codes for this sniff were unstable as they were based on the code being analysed instead of on fixed values.- Various bugfixes for the
WordPress.WP.GlobalVariablesOverride
sniff:- Previously, the sniff only checked variables in the global namespace when a
global
statement would be encountered. As of now, all variable assignments in the global namespace will be checked. - Nested functions/closures/classes which don't import the global variable will now be skipped over when encountered within another function, preventing false positives.
- Parameters in function declarations will no longer throw false positives.
- The error message for assignments to a subkey of the
$GLOBALS
superglobal has been improved. - Various efficiency improvements.
- Previously, the sniff only checked variables in the global namespace when a
- The
Sniff::is_in_isset_or_empty()
method presumed the WordPress coding style regarding code layout, which could lead to incorrect results (mostly underreporting).
This affected, amongst others, theWordPress.Security.ValidatedSanitizedInput
sniff. - Broken links in the inline developer documentation.