Releases: WordPress/WordPress-Coding-Standards
3.1.0
Added
- WordPress-Core ruleset: now includes the
Universal.PHP.LowercasePHPTag
sniff. - WordPress-Extra ruleset: now includes the
Generic.CodeAnalysis.RequireExplicitBooleanOperatorPrecedence
and theUniversal.CodeAnalysis.NoDoubleNegative
sniffs. - The
sanitize_locale_name()
function to the list of known "escaping" functions. Props @Chouby - The
sanitize_locale_name()
function to the list of known "sanitize & unslash" functions. Props @Chouby
Changed
- The minimum required
PHP_CodeSniffer
version to 3.9.0 (was 3.7.2). - The minimum required
PHPCSUtils
version to 1.0.10 (was 1.0.8). - The minimum required
PHPCSExtra
version to 1.2.1 (was 1.1.0).
Please ensure you runcomposer update wp-coding-standards/wpcs --with-dependencies
to benefit from these updates. - Core ruleset: the spacing after the
use
keyword for closureuse
statements will now consistently be checked. Props @westonruter for reporting. - The default value for
minimum_wp_version
, as used by a number of sniffs detecting usage of deprecated WP features, has been updated to6.2
. WordPress.NamingConventions.PrefixAllGlobals
has been updated to recognize pluggable functions introduced in WP 6.4 and 6.5.WordPress.NamingConventions.ValidPostTypeSlug
has been updated to recognize reserved post types introduced in WP 6.4 and 6.5.WordPress.WP.ClassNameCase
has been updated to recognize classes introduced in WP 6.4 and 6.5.WordPress.WP.DeprecatedClasses
now detects classes deprecated in WordPress up to WP 6.5.WordPress.WP.DeprecatedFunctions
now detects functions deprecated in WordPress up to WP 6.5.- The
IsUnitTestTrait
will now recognize classes which extend the new WP CoreWP_Font_Face_UnitTestCase
class as test classes. - The test suite can now run on PHPUnit 4.x - 9.x (was 4.x - 7.x), which should make contributing more straight forward.
- Various housekeeping, includes a contribution from @rodrigoprimo.
Fixed
WordPress.WP.PostsPerPage
could potentially result in anInternal.Exception
when encountering a query string which doesn't include the value forposts_per_page
in the query string. Props @anomiex for reporting.
3.0.1
Added
- In WordPressCS 3.0.0, the functionality of the
WordPress.Security.EscapeOutput
sniff was updated to report unescaped message parameters passed to exceptions created inthrow
statements. This specific violation now has a separate error code:ExceptionNotEscaped
. This will allow users to ignore or exclude that specific error code. Props @anomiex.
The error code(s) for other escaping issues flagged by the sniff remain unchanged.
Changed
- Updated the CI workflow to test the example ruleset for issues.
- Funding files and updates in the Readme about funding the project.
Fixed
- Fixed a sniff name in the
phpcs.xml.dist.sample
file (case-sensitive sniff name). Props @dawidurbanski.
3.0.0
Important information about this release:
At long last... WordPressCS 3.0.0 is here.
This is an important release which makes significant changes to improve the accuracy, performance, stability and maintainability of all sniffs, as well as making WordPressCS much better at handling modern PHP.
WordPressCS 3.0.0 contains breaking changes, both for people using ignore annotations, people maintaining custom rulesets, as well as for sniff developers who maintain a custom PHPCS standard based on WordPressCS.
If you are an end-user or maintain a custom WordPressCS based ruleset, please start by reading the Upgrade Guide to WordPressCS 3.0.0 for ruleset maintainers which lists the most important changes and contains a step by step guide for upgrading.
If you are a maintainer of an external standard based on WordPressCS and any of your custom sniffs are based on or extend WordPressCS sniffs, please read the Upgrade Guide to WordPressCS 3.0.0 for Developers.
In all cases, please read the complete changelog carefully before you upgrade.
Added
- Dependencies on the following packages: PHPCSUtils, PHPCSExtra and the [Composer PHPCS plugin].
- A best effort has been made to add support for the new PHP syntaxes/features to all WordPressCS native sniffs and utility functions (or to verify/improve existing support).
While support in external sniffs used by WordPressCS has not be exhaustively verified, a lot of work has been done to try and add support for new PHP syntaxes to those as well.
WordPressCS native sniffs and utilities have received fixes for the following syntaxes:- PHP 7.2
- Keyed lists.
- PHP 7.3
- Flexible heredoc/nowdoc (providing the PHPCS scan is run on PHP 7.3 or higher).
- Trailing commas in function calls.
- PHP 7.4
- Arrow functions.
- Array unpacking in array expressions.
- Numeric literals with underscores.
- Typed properties.
- Null coalesce equals operator.
- PHP 8.0
- Nullsafe object operators.
- Match expressions.
- Named arguments in function calls.
- Attributes.
- Union types // including supporting the
false
andnull
types. - Constructor property promotion.
$object::class
- Throw as an expression.
- PHP 8.1
- Enumerations.
- Explicit octal notation.
- Final class constants
- First class callables.
- Intersection types.
- PHP 8.2
- Constants in traits.
- PHP 7.2
- New
WordPress.CodeAnalysis.AssignmentInTernaryCondition
sniff to theWordPress-Core
ruleset which partially replaces the removedWordPress.CodeAnalysis.AssignmentInCondition
sniff. - New
WordPress.WhiteSpace.ObjectOperatorSpacing
sniff which replaces the use of theSquiz.WhiteSpace.ObjectOperatorSpacing
sniff in theWordPress-Core
ruleset. - New
WordPress.WP.ClassNameCase
sniff to theWordPress-Core
ruleset, to check that any class name references to WP native classes and classes from external dependencies use the case of the class as per the class declaration. - New
WordPress.WP.Capabilities
sniff to theWordPress-Extra
ruleset. This sniff checks that valid capabilities are used, not roles or user levels. Props, amongst others, to [@grappler] and [@khacoder].
Custom capabilities can be added to the sniff via acustom_capabilities
ruleset property.
The sniff also supports theminimum_wp_version
property to allow the sniff to accurately determine how the use of deprecated capabilities should be flagged. - The
WordPress.WP.CapitalPDangit
sniff contains a new check to verify the correct spelling ofWordPress
in namespace names. - The
WordPress.WP.I18n
sniff contains a newEmptyTextDomain
error code for an empty text string being passed as the text domain, which overrules the default value of the parameter and renders a text untranslatable. - The
WordPress.DB.PreparedSQLPlaceholders
sniff has been expanded with additional checks for the correct use of the%i
placeholder, which was introduced in WP 6.2. Props [@craigfrancis].
The sniff now also supports theminimum_wp_version
ruleset property to determine whether the%i
placeholder can be used. WordPress-Core
: the following additional sniffs (or select error codes from these sniffs) have been added to the ruleset:Generic.CodeAnalysis.AssignmentInCondition
,Generic.CodeAnalysis.EmptyPHPStatement
(replaces the WordPressCS native sniff),Generic.VersionControl.GitMergeConflict
,Generic.WhiteSpace.IncrementDecrementSpacing
,Generic.WhiteSpace.LanguageConstructSpacing
,Generic.WhiteSpace.SpreadOperatorSpacingAfter
,PSR2.Classes.ClassDeclaration
,PSR2.Methods.FunctionClosingBrace
,PSR12.Classes.ClassInstantiation
,PSR12.Files.FileHeader
(select error codes only),PSR12.Functions.NullableTypeDeclaration
,PSR12.Functions.ReturnTypeDeclaration
,PSR12.Traits.UseDeclaration
,Squiz.Functions.MultiLineFunctionDeclaration
(replaces part of theWordPress.WhiteSpace.ControlStructureSpacing
sniff),Modernize.FunctionCalls.Dirname
,NormalizedArrays.Arrays.ArrayBraceSpacing
(replaces part of theWordPress.Arrays.ArrayDeclarationSpacing
sniff),NormalizedArrays.Arrays.CommaAfterLast
(replaces the WordPressCS native sniff),Universal.Classes.ModifierKeywordOrder
,Universal.Classes.RequireAnonClassParentheses
,Universal.Constants.LowercaseClassResolutionKeyword
,Universal.Constants.ModifierKeywordOrder
,Universal.Constants.UppercaseMagicConstants
,Universal.Namespaces.DisallowCurlyBraceSyntax
,Universal.Namespaces.DisallowDeclarationWithoutName
,Universal.Namespaces.OneDeclarationPerFile
,Universal.NamingConventions.NoReservedKeywordParameterNames
,Universal.Operators.DisallowShortTernary
(replaces the WordPressCS native sniff),Universal.Operators.DisallowStandalonePostIncrementDecrement
,Universal.Operators.StrictComparisons
(replaces the WordPressCS native sniff),Universal.Operators.TypeSeparatorSpacing
,Universal.UseStatements.DisallowMixedGroupUse
,Universal.UseStatements.KeywordSpacing
,Universal.UseStatements.LowercaseFunctionConst
,Universal.UseStatements.NoLeadingBackslash
,Universal.UseStatements.NoUselessAliases
,Universal.WhiteSpace.CommaSpacing
,Universal.WhiteSpace.DisallowInlineTabs
(replaces the WordPressCS native sniff),Universal.WhiteSpace.PrecisionAlignment
(replaces the WordPressCS native sniff),Universal.WhiteSpace.AnonClassKeywordSpacing
.WordPress-Extra
: the following additional sniffs have been added to the ruleset:Generic.CodeAnalysis.UnusedFunctionParameter
,Universal.Arrays.DuplicateArrayKey
,Universal.CodeAnalysis.ConstructorDestructorReturn
,Universal.CodeAnalysis.ForeachUniqueAssignment
,Universal.CodeAnalysis.NoEchoSprintf
,Universal.CodeAnalysis.StaticInFinalClass
,Universal.ControlStructures.DisallowLonelyIf
,Universal.Files.SeparateFunctionsFromOO
.WordPress.Utils.I18nTextDomainFixer
: theload_script_textdomain()
function to the functions the sniff looks for.WordPress.WP.AlternativeFunctions
: the following PHP native functions have been added to the sniff and will now be flagged when used:unlink()
(in a newunlink
group) ,rename()
(in a newrename
group),chgrp()
,chmod()
,chown()
,is_writable()
is_writeable()
,mkdir()
,rmdir()
,touch()
,fputs()
(in the existingfile_system_operations
group, which was previously namedfile_system_read
). Props [@sandeshjangam] and [@JDGrimes].- The
PHPUnit_Adapter_TestCase
class to the list of "known test (case) classes". - The
antispambot()
function to the list of known "formatting" functions. - The
esc_xml()
andwp_kses_one_attr()
functions to the list of known "escaping" functions. - The
wp_timezone_choice()
andwp_readonly()
functions to the list of known "auto escaping" functions. - The
sanitize_url()
andwp_kses_one_attr()
functions to the list of known "sanitizing" functions. - Metrics for blank lines at the start/end of a control structure body to the
WordPress.WhiteSpace.ControlStructureSpacing
sniff. These can be displayed using--report=info
when theblank_line_check
property has been set totrue
. - End-user documentation to the following new and pre-existing sniffs:
WordPress.DateTime.RestrictedFunctions
,WordPress.NamingConventions.PrefixAllGlobals
(props [@Ipstenu]),WordPress.PHP.StrictInArray
(props [@marconmartins]),WordPress.PHP.YodaConditions
(props [@Ipstenu]),WordPress.WhiteSpace.ControlStructureSpacing
(props [@ckanitz]),WordPress.WhiteSpace.ObjectOperatorSpacing
,WordPress.WhiteSpace.OperatorSpacing
(props [@ckanitz]),WordPress.WP.CapitalPDangit
(props [@NielsdeBlaauw]),WordPress.WP.Capabilities
,WordPress.WP.ClassNameCase
,WordPress.WP.EnqueueResourceParameters
(props [@NielsdeBlaauw]).
This documentation can be exposed via thePHP_CodeSniffer
--generator=...
command-line argument.
Note: all sniffs which have been added from PHPCSExtra (Universal, Modernize, NormalizedArrays sniffs) are also fully documented.
Added (internal/dev-only)
- New Helper classes:
ArrayWalkingFunctionsHelper
ConstantsHelper
*ContextHelper
*DeprecationHelper
*FormattingFunctionsHelper
ListHelper
*RulesetPropertyHelper
*SnakeCaseHelper
*UnslashingFunctionsHelper
ValidationHelper
VariableHelper
*
...
2.3.0
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.
2.2.1
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.
2.2.0
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.
2.1.1
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.
2.1.0
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.
2.0.0
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:
2.0.0-RC1
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 the `Abstract...