PHP_CodeSniffer rules (sniffs) to enforce WordPress coding conventions
Universal.PHP.LowercasePHPTag
sniff.Generic.CodeAnalysis.RequireExplicitBooleanOperatorPrecedence
and the Universal.CodeAnalysis.NoDoubleNegative
sniffs.sanitize_locale_name()
function to the list of known "escaping" functions. Props @Choubysanitize_locale_name()
function to the list of known "sanitize & unslash" functions. Props @ChoubyPHP_CodeSniffer
version to 3.9.0 (was 3.7.2).PHPCSUtils
version to 1.0.10 (was 1.0.8).PHPCSExtra
version to 1.2.1 (was 1.1.0).
Please ensure you run composer update wp-coding-standards/wpcs --with-dependencies
to benefit from these updates.use
keyword for closure use
statements will now consistently be checked. Props @westonruter for reporting.minimum_wp_version
, as used by a number of sniffs detecting usage of deprecated WP features, has been updated to 6.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.IsUnitTestTrait
will now recognize classes which extend the new WP Core WP_Font_Face_UnitTestCase
class as test classes.WordPress.WP.PostsPerPage
could potentially result in an Internal.Exception
when encountering a query string which doesn't include the value for posts_per_page
in the query string. Props @anomiex for reporting.WordPress.Security.EscapeOutput
sniff was updated to report unescaped message parameters passed to exceptions created in throw
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.phpcs.xml.dist.sample
file (case-sensitive sniff name). Props @dawidurbanski.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.
false
and null
types.$object::class
WordPress.CodeAnalysis.AssignmentInTernaryCondition
sniff to the WordPress-Core
ruleset which partially replaces the removed WordPress.CodeAnalysis.AssignmentInCondition
sniff.WordPress.WhiteSpace.ObjectOperatorSpacing
sniff which replaces the use of the Squiz.WhiteSpace.ObjectOperatorSpacing
sniff in the WordPress-Core
ruleset.WordPress.WP.ClassNameCase
sniff to the WordPress-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.WordPress.WP.Capabilities
sniff to the WordPress-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 a custom_capabilities
ruleset property.
The sniff also supports the minimum_wp_version
property to allow the sniff to accurately determine how the use of deprecated capabilities should be flagged.WordPress.WP.CapitalPDangit
sniff contains a new check to verify the correct spelling of WordPress
in namespace names.WordPress.WP.I18n
sniff contains a new EmptyTextDomain
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.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 the minimum_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 the WordPress.WhiteSpace.ControlStructureSpacing
sniff), Modernize.FunctionCalls.Dirname
, NormalizedArrays.Arrays.ArrayBraceSpacing
(replaces part of the WordPress.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
: the load_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 new unlink
group) , rename()
(in a new rename
group), chgrp()
, chmod()
, chown()
, is_writable()
is_writeable()
, mkdir()
, rmdir()
, touch()
, fputs()
(in the existing file_system_operations
group, which was previously named file_system_read
). Props @sandeshjangam and @JDGrimes.PHPUnit_Adapter_TestCase
class to the list of "known test (case) classes".antispambot()
function to the list of known "formatting" functions.esc_xml()
and wp_kses_one_attr()
functions to the list of known "escaping" functions.wp_timezone_choice()
and wp_readonly()
functions to the list of known "auto escaping" functions.sanitize_url()
and wp_kses_one_attr()
functions to the list of known "sanitizing" functions.WordPress.WhiteSpace.ControlStructureSpacing
sniff. These can be displayed using --report=info
when the blank_line_check
property has been set to true
.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 the PHP_CodeSniffer
--generator=...
command-line argument.
Note: all sniffs which have been added from PHPCSExtra (Universal, Modernize, NormalizedArrays sniffs) are also fully documented.ArrayWalkingFunctionsHelper
ConstantsHelper
*ContextHelper
*DeprecationHelper
*FormattingFunctionsHelper
ListHelper
*RulesetPropertyHelper
*SnakeCaseHelper
*UnslashingFunctionsHelper
ValidationHelper
VariableHelper
*WPGlobalVariablesHelper
WPHookHelper
EscapingFunctionsTrait
IsUnitTestTrait
MinimumWPVersionTrait
PrintingFunctionsTrait
SanitizationHelperTrait
*WPDBTrait
These classes and traits mostly contain pre-existing functionality moved from the Sniff
class.
The classes marked with an *
are considered internal and do not have any promise of future backward compatibility.
More information is available in the Upgrade Guide to WordPressCS 3.0.0 for Developers.
PHP_CodeSniffer
version to 3.7.2 (was 3.3.1).filter
, libxml
and XMLReader
extensions are now explicitly required.
It is recommended to also have the Mbstring
and iconv
extensions enabled for the most accurate results.master
to main
.WordPress-Extra
to WordPress-Core
: the Generic.Files.OneObjectStructurePerFile
(also changed from warning
to error
),
Generic.PHP.BacktickOperator
, PEAR.Files.IncludingFile
, PSR2.Classes.PropertyDeclaration
, PSR2.Methods.MethodDeclaration
, Squiz.Scope.MethodScope
, Squiz.WhiteSpace.ScopeKeywordSpacing
sniffs. Props, amongst others, to @desrosj.WordPress-Core
: The Generic.Arrays.DisallowShortArraySyntax
sniff has been replaced by the Universal.Arrays.DisallowShortArraySyntax
sniff.
The new sniff will recognize short lists correctly and ignore them.WordPress-Core
: The Generic.Files.EndFileNewline
sniff has been replaced by the more comprehensive PSR2.Files.EndFileNewline
sniff.minimum_supported_version
property for each sniff from a ruleset.--runtime-set minimum_supported_wp_version #.#
on the command line.
The names of the property and the CLI setting have now been aligned to both use minimum_wp_version
as the name.
Both ways of passing the value are still supported.WordPress.NamingConventions.PrefixAllGlobals
: the custom_test_class_whitelist
property has been renamed to custom_test_classes
.WordPress.NamingConventions.ValidVariableName
: the customPropertiesWhitelist
property has been renamed to allowed_custom_properties
.WordPress.PHP.NoSilencedErrors
: the custom_whitelist
property has been renamed to customAllowedFunctionsList
.WordPress.PHP.NoSilencedErrors
: the use_default_whitelist
property has been renamed to usePHPFunctionsList
.WordPress.WP.GlobalVariablesOverride
: the custom_test_class_whitelist
property has been renamed to custom_test_classes
.custom_test_classes
(previously custom_test_class_whitelist
) ruleset property.minimum_supported_wp_version
, as used by a number of sniffs detecting usage of deprecated WP features, has been updated to 6.0
.WordPress.NamingConventions.PrefixAllGlobals
now takes new pluggable constants into account as introduced in WordPress up to WP 6.3.WordPress.NamingConventions.ValidPostTypeSlug
now takes new reserved post types into account as introduced in WordPress up to WP 6.3.WordPress.WP.DeprecatedClasses
now detects classes deprecated in WordPress up to WP 6.3.WordPress.WP.DeprecatedFunctions
now detects functions deprecated in WordPress up to WP 6.3.WordPress.WP.DeprecatedParameters
now detects parameters deprecated in WordPress up to WP 6.3.WordPress.WP.DeprecatedParameterValues
now detects parameter values deprecated in WordPress up to WP 6.3.WordPress.Utils.I18nTextDomainFixer
: the lists of recognized plugin and theme header tags has been updated based on the current information in the plugin and theme handbooks.WordPress.WP.AlternativeFunctions
: the "group" name file_system_read
, which can be used with the exclude
property, has been renamed to file_system_operations
.
This also means that the error codes for individual functions flagged via that group have changed from WordPress.WP.AlternativeFunctions.file_system_read_*
to WordPress.WP.AlternativeFunctions.file_system_operations_*
.WordPress.WP.CapitalPDangit
: the Misspelled
error code has been split into two error codes - MisspelledInText
and MisspelledInComment
- to allow for more modular exclusions/selectively turning off the auto-fixer for the sniff.WordPress.WP.I18n
no longer throws both the MissingSingularPlaceholder
and the MismatchedPlaceholders
for the same code, as the errors have an overlap.WordPress-Core
: previously only the spacing around commas in arrays, function declarations and function calls was checked. Now, the spacing around commas will be checked in all contexts.WordPress.Arrays.ArrayKeySpacingRestrictions
: a new SpacesBetweenBrackets
error code has been introduced for the spacing between square brackets for array assignments without key. Previously, this would throw a NoSpacesAroundArrayKeys
error with an unclear error message.WordPress.Files.FileName
now recognizes more word separators, meaning that files using other word separators than underscores will now be flagged for not using hyphenation.WordPress.Files.FileName
now checks if a file contains a test class and if so, will bow out.
This change was made to prevent issues with PHPUnit 9.1+, which strongly prefers PSR4-style file names.
Whether something is test class or not is based on a pre-defined list of "known" test case classes which can be extended and, optionally, a list of user provided test case classes provided via setting the custom_test_classes
property in a custom ruleset or the complete test directory can be excluded via a custom ruleset.WordPress.NamingConventions.PrefixAllGlobals
now allows for pluggable functions and classes, which should not be prefixed when "plugged".WordPress.PHP.NoSilencedErrors
: the metric, which displays in the info
report, has been renamed from "whitelisted function call" to "silencing allowed function call".WordPress.Security.EscapeOutput
now flags the use of get_search_query( false )
when generating output (as the false
turns off the escaping).WordPress.Security.EscapeOutput
now also examines parameters passed for exception creation in throw
statements and expressions for correct escaping.WordPress.Security.ValidatedSanitizedInput
now examines all superglobal (except for $GLOBALS
). Previously, the $_SESSION
and $_ENV
superglobals would not be flagged as needing validation/sanitization.WordPress.WP.I18n
now recognizes the new PHP 8.0+ h
and H
type specifiers.WordPress.WP.PostsPerPage
has improved recognition for numbers prefixed with a unary operator and non-decimal numbers.WordPress.DB.PreparedSQL
will identify more precisely the code which is problematic.WordPress.DB.PreparedSQLPlaceholders
will identify more precisely the code which is problematic.WordPress.DB.SlowDBQuery
will identify more precisely the code which is problematic.WordPress.Security.PluginMenuSlug
: the error will now be thrown more precisely on the code which triggered the error. Depending on code layout, this may mean that an error will now be thrown on a different line.WordPress.WP.DiscouragedConstants
: the error will now be thrown more precisely on the code which triggered the error. Depending on code layout, this may mean that an error will now be thrown on a different line.WordPress.WP.EnqueuedResourceParameters
: the error will now be thrown more precisely on the code which triggered the error. Depending on code layout, this may mean that an error will now be thrown on a different line.WordPress.WP.I18n
: the errors will now be thrown more precisely on the code which triggered the error. Depending on code layout, this may mean that an error will now be thrown on a different line.WordPress.WP.PostsPerPage
will identify more precisely the code which is problematic.WordPress.PHP.TypeCasts.UnsetFound
has been changed from a warning
to an error
as the (unset)
cast is no longer available in PHP 8.0 and higher.WordPress.WP.EnqueuedResourceParameters.MissingVersion
has been changed from an error
to a warning
.WordPress.Arrays.ArrayKeySpacingRestrictions
: improved the clarity of the error messages for the TooMuchSpaceBeforeKey
and TooMuchSpaceAfterKey
error codes.WordPress.CodeAnalysis.EscapedNotTranslated
: improved the clarity of the error message.WordPress.PHP.IniSet
: improved the clarity of the error messages for the sniff.WordPress.PHP.PregQuoteDelimiter
: improved the clarity of the error message for the Missing
error code.WordPress.PHP.RestrictedFunctions
: improved the clarity of the error messages for the sniff.WordPress.PHP.RestrictedPHPFunctions
: improved the error message for the create_function_create_function
error code.WordPress.PHP.TypeCast
: improved the clarity of the error message for the UnsetFound
error code. It will no longer advise assigning null
.WordPress.Security.SafeRedirect
: improved the clarity of the error message. (very minor)WordPress.Security.ValidatedSanitizedInput
: improved the clarity of the error messages for the MissingUnslash
error code.WordPress.WhiteSpace.CastStructureSpacing
: improved the clarity of the error message for the NoSpaceBeforeOpenParenthesis
error code.WordPress.WP.I18n
: improved the clarity of the error messages for the sniff.WordPress.WP.I18n
: the error messages will now use the correct parameter name.WordPress.CodeAnalysis.EscapedNotTranslated
, WordPress.NamingConventions.PrefixAllGlobals
, WordPress.NamingConventions.ValidPostTypeSlug
, WordPress.PHP.IniSet
, and the WordPress.PHP.NoSilencedErrors
sniff will now display the code sample found without comments and extranuous whitespace.final
with the exception of the following four classes which are known to be extended by external PHPCS standards build on top of WordPressCS: WordPress.NamingConventions.ValidHookName
, WordPress.Security.EscapeOutput
,WordPress.Security.NonceVerification
, WordPress.Security.ValidatedSanitizedInput
.WordPressCS\WordPress\Sniff
class, have been moved to dedicated Helper classes and traits or, in some cases, to the sniff class using them.
As this change is only relevant for extenders, the full details of these moves are not included in this changelog, but can be found in the Developers Upgrade Guide to WordPressCS 3.0.0
public
properties, which were used by multiple sniffs, have been moved from *Sniff
classes to traits. Again, the full details of these moves are not included in this changelog, but can be found in the Developers Upgrade Guide to WordPressCS 3.0.0
AbstractFunctionRestrictionsSniff
: The whitelist
key in the $groups
array property has been renamed to allow
.WordPress.NamingConventions.ValidFunctionName
sniff no longer extends the similar PHPCS native PEAR
sniff.WordPress.Arrays.CommaAfterArrayItem
sniff (replaced by the NormalizedArrays.Arrays.CommaAfterLast
and the Universal.WhiteSpace.CommaSpacing
sniffs).WordPress.Classes.ClassInstantiation
sniff (replaced by the PSR12.Classes.ClassInstantiation
, Universal.Classes.RequireAnonClassParentheses
and Universal.WhiteSpace.AnonClassKeywordSpacing
sniffs).WordPress.CodeAnalysis.AssignmentInCondition
sniff (replaced by the Generic.CodeAnalysis.AssignmentInCondition
and the WordPress.CodeAnalysis.AssignmentInTernaryCondition
sniffs).WordPress.CodeAnalysis.EmptyStatement
sniff (replaced by the Generic.CodeAnalysis.EmptyPHPStatement
sniff).WordPress.PHP.DisallowShortTernary
sniff (replaced by the Universal.Operators.DisallowShortTernary
sniff).WordPress.PHP.StrictComparisons
sniff (replaced by the Universal.Operators.StrictComparisons
sniff).WordPress.WhiteSpace.DisallowInlineTabs
sniff (replaced by the Universal.WhiteSpace.DisallowInlineTabs
sniff).WordPress.WhiteSpace.PrecisionAlignment
sniff (replaced by the Universal.WhiteSpace.PrecisionAlignment
sniff).WordPress.WP.TimezoneChange
sniff (replaced by the WordPress.DateTime.RestrictedFunctions
sniff). This sniff was previously already deprecated.WordPress-Extra
: The Squiz.WhiteSpace.LanguageConstructSpacing
sniff (replaced by the added, more comprehensive Generic.WhiteSpace.LanguageConstructSpacing
sniff in the WordPress-Core
ruleset).WordPress.Arrays.ArrayDeclarationSpacing
: array brace spacing checks (replaced by the NormalizedArrays.Arrays.ArrayBraceSpacing
sniff).WordPress.WhiteSpace.ControlStructureSpacing
: checks for the spacing for function declarations (replaced by the Squiz.Functions.MultiLineFunctionDeclaration
sniff).
Includes removal of the spaces_before_closure_open_paren
property for this sniff.WordPress.WP.I18n
: the check_translator_comments
property.
Exclude the WordPress.WP.I18n.MissingTranslatorsComment
and the WordPress.WP.I18n.TranslatorsCommentWrongStyle
error codes instead.PHPCompatibilityWP
standard to check for PHP cross-version compatibility issues.WordPress.Arrays.ArrayKeySpacingRestrictions.MissingBracketCloser
error code as sniffs should not report on parse errors.WordPress.CodeAnalysis.AssignmentIn[Ternary]Condition.NonVariableAssignmentFound
error code as sniffs should not report on parse errors.Block_Supported_Styles_Test
class will no longer incorrectly be recognized as an extendable test case class.AbstractArrayAssignmentRestrictionsSniff
: support for the optional 'callback'
key in the array returned by getGroups()
.WordPressCS\WordPress\PHPCSHelper
class (use the PHPCSUtils\BackCompat\Helper
class instead).WordPressCS\WordPress\Sniff::addMessage()
method (use the PHPCSUtils\Utils\MessageHelper::addMessage()
method instead).WordPressCS\WordPress\Sniff::addFixableMessage()
method (use the PHPCSUtils\Utils\MessageHelper::addFixableMessage()
method instead).WordPressCS\WordPress\Sniff::determine_namespace()
method (use the PHPCSUtils\Utils\Namespaces::determineNamespace()
method instead).WordPressCS\WordPress\Sniff::does_function_call_have_parameters()
method (use the PHPCSUtils\Utils\PassedParameters::hasParameters()
method instead).WordPressCS\WordPress\Sniff::find_array_open_close()
method (use the PHPCSUtils\Utils\Arrays::getOpenClose()
method instead).WordPressCS\WordPress\Sniff::find_list_open_close()
method (use the PHPCSUtils\Utils\Lists::getOpenClose()
method instead).WordPressCS\WordPress\Sniff::get_declared_namespace_name()
method (use the PHPCSUtils\Utils\Namespaces::getDeclaredName()
method instead).WordPressCS\WordPress\Sniff::get_function_call_parameter_count()
method (use the PHPCSUtils\Utils\PassedParameters::getParameterCount()
method instead).WordPressCS\WordPress\Sniff::get_function_call_parameters()
method (use the PHPCSUtils\Utils\PassedParameters::getParameters()
method instead).WordPressCS\WordPress\Sniff::get_function_call_parameter()
method (use the PHPCSUtils\Utils\PassedParameters::getParameter()
method instead).WordPressCS\WordPress\Sniff::get_interpolated_variables()
method (use the PHPCSUtils\Utils\TextStrings::getEmbeds()
method instead).WordPressCS\WordPress\Sniff::get_last_ptr_on_line()
method (no replacement available at this time).WordPressCS\WordPress\Sniff::get_use_type()
method (use the PHPCSUtils\Utils\UseStatements::getType()
method instead).WordPressCS\WordPress\Sniff::has_whitelist_comment()
method (no replacement).WordPressCS\WordPress\Sniff::$hookFunctions
property (no replacement available at this time).WordPressCS\WordPress\Sniff::init()
method (no replacement).WordPressCS\WordPress\Sniff::is_class_constant()
method (use the PHPCSUtils\Utils\Scopes::isOOConstant()
method instead).WordPressCS\WordPress\Sniff::is_class_property()
method (use the PHPCSUtils\Utils\Scopes::isOOProperty()
method instead).WordPressCS\WordPress\Sniff::is_foreach_as()
method (use the PHPCSUtils\Utils\Context::inForeachCondition()
method instead).WordPressCS\WordPress\Sniff::is_short_list()
method (depending on your needs, use the PHPCSUtils\Utils\Lists::isShortList()
or the PHPCSUtils\Utils\Arrays::isShortArray()
method instead).WordPressCS\WordPress\Sniff::is_token_in_test_method()
method (no replacement available at this time).WordPressCS\WordPress\Sniff::REGEX_COMPLEX_VARS
constant (use the PHPCSUtils PHPCSUtils\Utils\TextStrings::stripEmbeds()
and PHPCSUtils\Utils\TextStrings::getEmbeds()
methods instead).WordPressCS\WordPress\Sniff::string_to_errorcode()
method (use the PHPCSUtils\Utils\MessageHelper::stringToErrorcode()
method instead).WordPressCS\WordPress\Sniff::strip_interpolated_variables()
method (use the PHPCSUtils\Utils\TextStrings::stripEmbeds()
method instead).WordPressCS\WordPress\Sniff::strip_quotes()
method (use the PHPCSUtils\Utils\TextStrings::stripQuotes()
method instead).WordPressCS\WordPress\Sniff::valid_direct_scope()
method (use the PHPCSUtils\Utils\Scopes::validDirectScope()
method instead).bin
directory.minimum_wp_version
property (previously minimum_supported_version
) will no longer throw a "passing null to non-nullable" deprecation notice on PHP 8.1+.WordPress.WhiteSpace.ControlStructureSpacing
no longer throws a TypeError
on PHP 8.0+.WordPress.NamingConventions.PrefixAllGlobals
no longer throws a "passing null to non-nullable" deprecation notice on PHP 8.1+.WordPress.WP.I18n
no longer throws a "passing null to non-nullable" deprecation notice on PHP 8.1+.VariableHelper::is_comparison()
(previously Sniff::is_comparison()
): fixed risk of undefined array key notice when scanning code containing parse errors.AbstractArrayAssignmentRestrictionsSniff
could previously get confused when it encountered comments in unexpected places.
This fix has a positive impact on all sniffs which are based on this abstract (2 sniffs).AbstractArrayAssignmentRestrictionsSniff
no longer examines numeric string keys as PHP treats those as integer keys, which were never intended as the target of this abstract.
This fix has a positive impact on all sniffs which are based on this abstract (2 sniffs).AbstractArrayAssignmentRestrictionsSniff
in case of duplicate entries, the sniff will now only examine the last value, as that's the value PHP will see.
This fix has a positive impact on all sniffs which are based on this abstract (2 sniffs).AbstractArrayAssignmentRestrictionsSniff
now determines the assigned value with higher accuracy.
This fix has a positive impact on all sniffs which are based on this abstract (2 sniffs).AbstractClassRestrictionsSniff
now treats the namespace
keyword when used as an operator case-insensitively.
This fix has a positive impact on all sniffs which are based on this abstract (3 sniffs).AbstractClassRestrictionsSniff
now treats the hierarchy keywords (self
, parent
, static
) case-insensitively.
This fix has a positive impact on all sniffs which are based on this abstract (3 sniffs).AbstractClassRestrictionsSniff
now limits itself correctly when trying to find a class name before a ::
.
This fix has a positive impact on all sniffs which are based on this abstract (3 sniffs).AbstractClassRestrictionsSniff
: false negatives on class instantiation statements ending on a PHP close tag.
This fix has a positive impact on all sniffs which are based on this abstract (3 sniffs).AbstractClassRestrictionsSniff
: false negatives on class instantiation statements combined with method chaining.
This fix has a positive impact on all sniffs which are based on this abstract (3 sniffs).AbstractFunctionRestrictionsSniff
: false positives on function declarations when the function returns by reference.
This fix has a positive impact on all sniffs which are based on this abstract (nearly half of the WordPressCS sniffs).AbstractFunctionRestrictionsSniff
: false positives on instantiation of a class with the same name as a targetted function.
This fix has a positive impact on all sniffs which are based on this abstract (nearly half of the WordPressCS sniffs).AbstractFunctionRestrictionsSniff
now respects that function names in PHP are case-insensitive in more places.
This fix has a positive impact on all sniffs which are based on this abstract (nearly half of the WordPressCS sniffs).minimum_wp_version
property (previously minimum_supported_version
) will now be more precise.WordPress.Arrays.ArrayIndentation
now ignores indentation issues for array items which are not the first thing on a line. This fixes a potential fixer conflict.WordPress.Arrays.ArrayKeySpacingRestrictions
: signed positive integer keys will now be treated the same as signed negative integer keys.WordPress.Arrays.ArrayKeySpacingRestrictions
: keys consisting of calculations will now be recognized more accurately.WordPress.Arrays.ArrayKeySpacingRestrictions.NoSpacesAroundArrayKeys
: now has better protection in case of a fixer conflict.WordPress.Classes.ClassInstantiation
could create parse errors when fixing a class instantiation using variable variables. This has been fixed by replacing the sniff with the PSR12.Classes.ClassInstantiation
sniff (and some others).WordPress.DB.DirectDatabaseQuery
could previously get confused when it encountered comments in unexpected places.WordPress.DB.DirectDatabaseQuery
now respects that function (method) names in PHP are case-insensitive.WordPress.DB.DirectDatabaseQuery
now only looks at the current statement to find a method call to the $wpdb
object.WordPress.DB.DirectDatabaseQuery
no longer warns about TRUNCATE
queries as those cannot be cached and need a direct database query.WordPress.DB.PreparedSQL
could previously get confused when it encountered comments in unexpected places.WordPress.DB.PreparedSQL
now respects that function names in PHP are case-insensitive.WordPress.DB.PreparedSQL
improved recognition of interpolated variables and expressions in the $text
argument. This fixes both some false negatives as well as some false positives.WordPress.DB.PreparedSQL
stricter recognition of the $wpdb
variable in double quoted query strings.WordPress.DB.PreparedSQL
false positive for floating point numbers concatenated into an SQL query.WordPress.DB.PreparedSQLPlaceholders
could previously get confused when it encountered comments in unexpected places.WordPress.DB.PreparedSQLPlaceholders
now respects that function names in PHP are case-insensitive.WordPress.DB.PreparedSQLPlaceholders
stricter recognition of the $wpdb
variable in double quotes query strings.WordPress.DB.PreparedSQLPlaceholders
false positive when a fully qualified function call is encountered in an implode( ', ', array_fill(...))
pattern.WordPress.Files.FileName
no longer presumes a three character file extension.WordPress.NamingConventions.PrefixAllGlobals
could previously get confused when it encountered comments in unexpected places in function calls which were being examined.WordPress.NamingConventions.PrefixAllGlobals
now respects that function names in PHP are case-insensitive when checking whether a function declaration is polyfilling a PHP native function.WordPress.NamingConventions.PrefixAllGlobals
improved false positive prevention for variable assignments via keyed lists.WordPress.NamingConventions.PrefixAllGlobals
now only looks at the current statement when determining which variables were imported via a global
statement. This prevents both false positives as well as false negatives.WordPress.NamingConventions.PrefixAllGlobals
no longer gets confused over global
statements in nested clsure/function declarations.WordPress.NamingConventions.ValidFunctionName
now also checks the names of (global) functions when the declaration is nested within an OO method.WordPress.NamingConventions.ValidFunctionName
no longer throws false positives for triple underscore methods.WordPress.NamingConventions.ValidFunctionName
the suggested replacement names in the error message no longer remove underscores from a name in case of leading or trailing underscores, or multiple underscores in the middle of a name.WordPress.NamingConventions.ValidFunctionName
the determination whether a name is in snake_case
is now more accurate and has improved handling of non-ascii characters.WordPress.NamingConventions.ValidFunctionName
now correctly recognizes a PHP4-style constructor when the class and the constructor method name contains non-ascii characters.WordPress.NamingConventions.ValidHookName
no longer throws false positives when the hook name is generated via a function call and that function is passed string literals as parameters.WordPress.NamingConventions.ValidHookName
now ignores parameters in a variable function call (like a call to a closure).WordPress.NamingConventions.ValidPostTypeSlug
no longer throws false positives for interpolated text strings with complex embedded variables/expressions.WordPress.NamingConventions.ValidVariableName
the suggested replacement names in the error message will no longer remove underscores from a name in case of leading or trailing underscores, or multiple underscores in the middle of a name.WordPress.NamingConventions.ValidVariableName
the determination whether a name is in snake_case
is now more accurate and has improved handling of non-ascii characters.WordPress.NamingConventions.ValidVariableName
now examines all variables and variables in expressions in a text string containing interpolation.WordPress.NamingConventions.ValidVariableName
now has improved recognition of variables in complex embedded variables/expressions in interpolated text strings.WordPress.PHP.IniSet
no longer gets confused over comments in the code when determining whether the ini value is an allowed one.WordPress.PHP.NoSilencedErrors
no longer throws an error when error silencing is encountered for function calls to the PHP native libxml_disable_entity_loader()
and imagecreatefromwebp()
methods.WordPress.PHP.StrictInArray
no longer gets confused over comments in the code when determining whether the $strict
parameter is used.WordPress.Security.EscapeOutput
no longer throws a false positive on function calls where the parameters need escaping, when no parameters are being passed.WordPress.Security.EscapeOutput
no longer throws a false positive when a fully qualified function call to the \basename()
function is encountered within a call to _deprecated_file()
.WordPress.Security.EscapeOutput
could previously get confused when it encountered comments in the $file
parameter for _deprecated_file()
.WordPress.Security.EscapeOutput
now ignores significantly more operators which should yield more accurate results.WordPress.Security.EscapeOutput
now respects that function names in PHP are case-insensitive when checking whether a printing function is being used.WordPress.Security.EscapeOutput
no longer throws an Internal.Exception
when it encounters a constant or property mirroring the name of one of the printing functions being targetted, nor will it throw false positives for those.WordPress.Security.EscapeOutput
no longer incorrectly handles method calls or calls to namespaced functions mirroring the name of one of the printing functions being targetted.WordPress.Security.EscapeOutput
now ignores exit
/die
statements without a status being passed, preventing false positives on code after the statement.WordPress.Security.EscapeOutput
now has improved recognition that print
can also be used as an expression, not only as a statement.WordPress.Security.EscapeOutput
now has much, much, much more accurate handling of code involving ternary expressions and should now correctly ignore the ternary condition in all long ternaries being examined.WordPress.Security.EscapeOutput
no longer disregards the ternary condition in a short ternary.WordPress.Security.EscapeOutput
no longer skips over a constant or property mirroring the name of one of the (auto-)escaping/formatting functions being targeted.WordPress.Security.EscapeOutput
no longer throws false positives for *::class
, which will always evaluate to a plain string.WordPress.Security.EscapeOutput
no longer throws false positives on output generating keywords encountered in an inline expression.WordPress.Security.EscapeOutput
no longer throws false positives on parameters passed to _e()
or _ex()
, which won't be used in the output.WordPress.Security.EscapeOutput
no longer throws false positives on heredocs not using interpolation.WordPress.Security.NonceVerification
now respects that function names in PHP are case-insensitive when checking whether an array comparison function is being used.WordPress.Security.NonceVerification
now also checks for nonce verification when the $_FILES
superglobal is being used.WordPress.Security.NonceVerification
now ignores properties named after superglobals.WordPress.Security.NonceVerification
now ignores list assignments to superglobals.WordPress.Security.NonceVerification
now ignores superglobals being unset.WordPress.Security.ValidatedSanitizedInput
now respects that function names in PHP are case-insensitive when checking whether an array comparison function is being used.WordPress.Security.ValidatedSanitizedInput
now respects that function names in PHP are case-insensitive when checking whether a variable is being validated using [array_]key_exists()
.WordPress.Security.ValidatedSanitizedInput
improved recognition of interpolated variables and expression in the text strings. This fixes some false negatives.WordPress.Security.ValidatedSanitizedInput
no longer incorrectly regards an unset()
as variable validation.WordPress.Security.ValidatedSanitizedInput
no longer incorrectly regards validation in a nested scope as validation which applies to the superglobal being examined.WordPress.WP.AlternativeFunctions
could previously get confused when it encountered comments in unexpected places.WordPress.WP.AlternativeFunctions
now correctly takes the minimum_wp_version
into account when determining whether a call to parse_url()
could switch over to using wp_parse_url()
.WordPress.WP.CapitalPDangit
now skips (keyed) list assignments to prevent false positives.WordPress.WP.CapitalPDangit
now always skips all array keys, not just plain text array keys.WordPress.WP.CronInterval
no longer throws a ChangeDetected
warning for interval calculations wrapped in parentheses, but for which the value for the interval is otherwise known.WordPress.WP.CronInterval
no longer throws a ChangeDetected
warning for interval calculations using fully qualified WP native time constants, but for which the value for the interval is otherwise known.WordPress.WP.DeprecatedParameters
no longer throws a false positive for function calls to comments_number()
using the fourth parameter (which was deprecated, but has been repurposed since WP 5.4).WordPress.WP.DeprecatedParameters
now looks for the correct parameter in calls to the unregister_setting()
function.WordPress.WP.DeprecatedParameters
now lists the correct WP version for the deprecation of the third parameter in function calls to get_user_option()
.WordPress.WP.DiscouragedConstants
could previously get confused when it encountered comments in unexpected places.WordPress.WP.EnqueuedResources
now recognizes enqueuing in a multi-line text string correctly.WordPress.WP.EnqueuedResourceParameters
could previously get confused when it encountered comments in unexpected places.WordPress.WP.GlobalVariablesOverride
improved false positive prevention for variable assignments via keyed lists.WordPress.WP.GlobalVariablesOverride
now only looks at the current statement when determining which variables were imported via a global
statement. This prevents both false positives as well as false negatives.WordPress.WP.I18n
improved recognition of interpolated variables and expression in the $text
argument. This fixes some false negatives.WordPress.WP.I18n
no longer potentially creates parse errors when auto-fixing an UnorderedPlaceholders*
error involving a multi-line text string.WordPress.WP.I18n
no longer throws false positives for compound parameters starting with a text string, which were previously checked as if the parameter only consisted of a text string.WordPress.WP.PostsPerPage
now determines the end of statement with more precision and will no longer throw a false positive for function calls on PHP 8.0+.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.minimum_supported_wp_version
, as used by a number of sniffs detecting usage of deprecated WP features, has been updated to 5.1
.WordPress.WP.DeprecatedFunctions
sniff will now detect functions deprecated in WP 5.4.WordPress.WP.DiscouragedFunctions
sniff.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.WordPress.Arrays.CommaAfterArrayItem
sniff. These can be displayed using --report=info
.sanitize_hex_color()
and the sanitize_hex_color_no_hash()
functions to the escapingFunctions
list used by the WordPress.Security.EscapeOutput
sniff.^0.6
.WordPress.PHP.NoSilencedErrors
: depending on the custom properties set, the metrics would be different.WordPress.WhiteSpace.ControlStructureSpacing
: fixed undefined index notice for closures with use
.WordPress.WP.GlobalVariablesOverride
: fixed undefined offset notice when the treat_files_as_scoped
property would be set to true
.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.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
.
WordPress.DateTime.CurrentTimeTimestamp
sniff to the WordPress-Core
ruleset, which checks against the use of the WP native current_time()
function to retrieve a timestamp as this won't be a real timestamp. Includes an auto-fixer.WordPress.DateTime.RestrictedFunctions
sniff to the WordPress-Core
ruleset, which checks for the use of certain date/time related functions. Initially this sniff forbids the use of the PHP native date_default_timezone_set()
and date()
functions.WordPress.PHP.DisallowShortTernary
sniff to the WordPress-Core
ruleset, which, as the name implies, disallows the use of short ternaries.WordPress.CodeAnalysis.EscapedNotTranslated
sniff to the WordPress-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.WordPress.NamingConventions.ValidPostTypeSlug
sniff to the WordPress-Extra
ruleset which will examine calls to register_post_type()
and throw errors when an invalid post type slug is used.Generic.Arrays.DisallowShortArraySyntax
to the WordPress-Core
ruleset.WordPress.NamingConventions.PrefixAllGlobals
: the PHP
prefix has been added to the prefix blacklist as it is reserved by PHP itself.wp_sanitize_redirect()
function to the sanitizingFunctions
list used by the WordPress.Security.NonceVerification
, WordPress.Security.ValidatedSanitizedInput
and WordPress.Security.EscapeOutput
sniffs.sanitize_key()
and the highlight_string()
functions to the escapingFunctions
list used by the WordPress.Security.EscapeOutput
sniff.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 the WordPress.Variables.GlobalVariables
and the WordPress.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 for list()
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 a list()
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.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 the PHP_CodeSniffer
--generator=...
command-line argument.minimum_supported_wp_version
, as used by a number of sniffs detecting usage of deprecated WP features, has been updated to 5.0
.WordPress.Arrays.ArrayKeySpacingRestrictions
sniff has two new error codes: TooMuchSpaceBeforeKey
and TooMuchSpaceAfterKey
. 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 new ShortPrefixPassed
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.WordPress.WP.DeprecatedClasses
sniff will now detect classes deprecated in WP 4.9 and WP 5.3.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.WordPress
ruleset by PHP_CodeSniffer
will now be faster.WordPress.WP.TimezoneChange
sniff. Use the WordPress.DateTime.RestrictedFunctions
instead.
The deprecated sniff will be removed in WPCS 3.0.0.WordPress.Arrays
category will no longer treat short lists as if they were a short array.WordPress.NamingConventions.ValidFunctionName
and the WordPress.NamingConventions.PrefixAllGlobals
sniff will now ignore functions marked as @deprecated
.WordPress.NamingConventions.PrefixAllGlobals
sniff as well as the WordPress.WP.GlobalVariablesOverride
sniff have been updated to recognize variables being declared via (long/short) list()
constructs and handle them correctly.WordPress.NamingConventions.PrefixAllGlobals
sniff as well as the WordPress.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 typical basename( __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.PHP_CodeSniffer
itself is only compatible with PHP 7.4 from PHPCS 3.5.0 onwards.WordPress.WP.CapitalPDangit
will now ignore misspelled instances of WordPress
within constant declarations.
This covers both constants declared using defined()
as well as constants declared using the const
keyword.minimum_supported_wp_version
, as used by a number of sniffs detecting usage of deprecated WP features, has been updated to 4.9
.paginate_comments_links()
from the list of auto-escaped functions Sniff::$autoEscapedFunctions
.
This affects the WordPress.Security.EscapeOutput
sniff.$current_blog
and $tag_ID
variables have been added to the list of WordPress global variables.
This fixes some false positives from the WordPress.NamingConventions.PrefixAllGlobals
and the WordPress.WP.GlobalVariablesOverride
sniffs.TestCase
class name has been added to the $test_class_whitelist
.
This fixes some false positives from the WordPress.NamingConventions.FileName
, WordPress.NamingConventions.PrefixAllGlobals
and the WordPress.WP.GlobalVariablesOverride
sniffs.WordPress.NamingConventions.ValidVariableName
sniff will now correctly recognize $tag_ID
as a WordPress native, mixed-case variable.WordPress.Security.NonceVerification
sniff will now correctly recognize nonce verification within a nested closure or anonymous class.WordPress.PHP.IniSet
sniff to the WordPress-Extra
ruleset.
This sniff will detect calls to ini_set()
and ini_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.
error
and advise using the alternative.doubleval()
, count()
and sizeof()
to Sniff::$unslashingSanitizingFunctions
property.
While count()
and its alias sizeof()
, don't actually unslash or sanitize, the output of these functions is safe to use without unslashing or sanitizing.
This affects the WordPress.Security.ValidatedSanitizedInput
and the WordPress.Security.NonceVerification
sniffs.WP_UnitTestCase_Base
class to the Sniff::$test_class_whitelist
property.Sniff::get_array_access_keys()
utility method to retrieve all array keys for a variable using multi-level array access.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.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).Sniff::is_in_type_test()
utility method to determine if a variable is being type tested, along with a Sniff::$typeTestFunctions
property containing the names of the functions this applies to.Sniff::is_in_array_comparison()
utility method to determine if a variable is (part of) a parameter in an array-value comparison, along with a Sniff::$arrayCompareFunctions
property containing the names of the relevant functions.Sniff::$arrayWalkingFunctions
property containing the names of array functions which apply a callback to the array, but don't change the array by reference.Sniff::$unslashingFunctions
property containing the names of functions which unslash data passed to them and return the unslashed result.WordPress.PHP.StrictComparisons
, WordPress.PHP.StrictInArray
and the WordPress.CodeAnalysis.AssignmentInCondition
sniff from the WordPress-Extra
to the WordPress-Core
ruleset.Squiz.Commenting.InlineComment.SpacingAfter
error is no longer included in the WordPress-Docs
ruleset.minimum_supported_wp_version
, as used by a number of sniffs detecting usage of deprecated WP features, has been updated to 4.8
.WordPress.WP.DeprecatedFunctions
sniff will now detect functions deprecated in WP 5.1.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.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.WordPress.Security.ValidatedSanitizedInput
sniff will now contain information on the index keys accessed.WordPress.Security.ValidatedSanitizedInput.InputNotValidated
has been reworded to make it more obvious what the actual issue being reported is.WordPress.Security.ValidatedSanitizedInput.MissingUnslash
has been reworded.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 to true
.^0.5.0
.ini_set
and ini_alter
from the list of functions detected by the WordPress.PHP.DiscouragedFunctions
sniff.
These are now covered via the new WordPress.PHP.IniSet
sniff.in_array()
and array_key_exists()
from the list of Sniff::$sanitizingFunctions
. These are now handled differently.WordPress.NamingConventions.PrefixAllGlobals
sniff would underreport when global functions would be autoloaded via a Composer autoload files
configuration.WordPress.Security.EscapeOutput
sniff will now recognize map_deep()
for escaping the values in an array via a callback to an output escaping function. This should prevent false positives.WordPress.Security.NonceVerification
sniff will no longer inadvertently allow for a variable to be sanitized without a nonce check within the same scope.WordPress.Security.ValidatedSanitizedInput
sniff will no longer throw errors when a variable is only being type tested.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.WordPress.WP.AlternativeFunctions
sniff will no longer recommend using the WP_FileSystem when PHP native input streams, like php://input
, or the PHP input stream constants are being read or written to.WordPress.WP.AlternativeFunctions
sniff will no longer report on usage of the curl_version()
function.WordPress.WP.CronInterval
sniff now has improved function recognition which should lower the chance of false positives.WordPress.WP.EnqueuedResources
sniff will no longer throw false positives for inline jQuery code trying to access a stylesheet link tag.Sniff::has_nonce_check()
method:
WordPress.Security.NonceVerification
sniff.Sniff::is_in_isset_or_empty()
method now also checks for usage of array_key_exist()
and key_exists()
and will regard these as correct ways to validate a variable.
This should prevent false positives for the WordPress.Security.ValidatedSanitizedInput
and the WordPress.Security.NonceVerification
sniffs.Sniff::is_sanitized()
method:
map_deep()
for sanitizing an array via a callback to a sanitization function. This should prevent false positives.stripslashes_deep()
and stripslashes_from_strings_only()
as valid unslashing functions. This should prevent false positives.
All these fixes affect both the WordPress.Security.ValidatedSanitizedInput
and the WordPress.Security.NonceVerification
sniff.Sniff::is_validated()
method:
array_key_exist()
and key_exists()
and will regard these as correct ways to validate a variable. This should prevent some false positives.WordPress.Security.ValidatedSanitizedInput
sniff should be more accurate because of these fixes.Sniff::is_assignment()
method.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.
WordPress-Extra
: Reverted back to including the Squiz.WhiteSpace.LanguageConstructSpacing
sniff instead of the new Generic.WhiteSpace.LanguageConstructSpacing
sniff as the new sniff is not (yet) available when the PEAR install of PHPCS is used.For a full list of changes from the 1.2.1 version, please review the following changelog:
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.
Generic.PHP.DiscourageGoto
, Generic.PHP.LowerCaseType
, Generic.WhiteSpace.ArbitraryParenthesesSpacing
and PSR12.Keywords.ShortFormTypeKeywords
to the WordPress-Core
ruleset.instanceof
operator to the WordPress.WhiteSpace.OperatorSpacing
sniff.PHP_CodeSniffer
version to 3.3.1 (was 2.9.0).WordPress
to WordPressCS\WordPress
.
This was not possible while PHP_CodeSniffer
2.x was still supported, but WordPressCS, as a good Open Source citizen, does not want to occupy the WordPress
namespace and is releasing its use of it now this is viable.WordPress.DB.PreparedSQL
sniff used the same error code for two different errors.
The NotPrepared
error code remains, however an additional InterpolatedNotPrepared
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.WordPress.NamingConventions.PrefixAllGlobals
sniff used the same error code for some errors as well as warnings.
The NonPrefixedConstantFound
error code remains for the related error, but the warning will now use the new VariableConstantNameFound
error code.
The NonPrefixedHooknameFound
error code remains for the related error, but the warning will now use the new DynamicHooknameFound
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.
NotSnakeCaseMemberVar
error code has been renamed to UsedPropertyNotSnakeCase
.NotSnakeCase
error code has been renamed to VariableNotSnakeCase
.MemberNotSnakeCase
error code has been renamed to PropertyNotSnakeCase
.StringNotSnakeCase
error code has been renamed to InterpolatedVariableNotSnakeCase
.
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.Security.NonceVerification
sniff used the same error code for both an error as well as a warning.
The old error code NoNonceVerification
is no longer used.
The error
now uses the Missing
error code, while the warning
now uses the Recommended
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.WordPress.WP.DiscouragedConstants
sniff used to have two error codes UsageFound
and DeclarationFound
.
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.WordPress.WP.GlobalVariablesOverride.OverrideProhibited
error code has been replaced by the WordPress.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 the Generic.Files.OneClassPerFile
, Generic.Files.OneInterfacePerFile
and the Generic.Files.OneTraitPerFile
sniffs with the new Generic.Files.OneObjectStructurePerFile
sniff.WordPress-Extra
: Replaced the inclusion of the Squiz.WhiteSpace.LanguageConstructSpacing
sniff with the new Generic.WhiteSpace.LanguageConstructSpacing
sniff.WordPress-Extra
: Replaced the inclusion of the Squiz.Scope.MemberVarScope
sniff with the more comprehensive PSR2.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.get_name_suggestion()
method has been moved from the WordPress.NamingConventions.ValidFunctionName
sniff to the base Sniff
class, renamed to get_snake_case_name_suggestion()
and made static.PHP_CodeSniffer
XSD schema.PHP_CodeSniffer
3.3.1+, including using the new array property format which is now supported.bin/pre-commit
example git hook has been updated to match. Additionally a run-tests
script has been added to the composer.json
file for your convenience.
To facilitate this, PHPUnit has been added to require-dev
, even though it is strictly speaking a dependency of PHPCS, not of WPCS.require-dev
.PHP_CodeSniffer
3.3.1+.PHP_CodeSniffer
3.2.0, as soon as possible.PHP_CodeSniffer
3.x.
Includes removing any and all workarounds which were in place to still support PHP 5.3.PHP_CodeSniffer
< 3.3.1.
Includes removing any and all workarounds which were in place for supporting older PHP_CodeSniffer
versions.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.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 minimum PHP_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.WordPress.Functions.FunctionCallSignatureNoParams
- superseded by a bug fix in the upstream PEAR.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 upstream Squiz.WhiteSpace.SemicolonSpacing
sniff.WordPress.WhiteSpace.ArbitraryParenthesesSpacing
- replaced by the same sniff which is now available upstream: Generic.WhiteSpace.ArbitraryParenthesesSpacing
.WordPress.Arrays.ArrayAssignmentRestrictions
- use the AbstractArrayAssignmentRestrictionsSniff
class instead.WordPress.Functions.FunctionRestrictions
- use the AbstractFunctionRestrictionsSniff
class instead.WordPress.Variables.VariableRestrictions
without replacement.WordPress.Arrays.ArrayDeclaration
- use the other sniffs in the WordPress.Arrays
category instead.WordPress.CSRF.NonceVerification
- use WordPress.Security.NonceVerification
instead.WordPress.Functions.DontExtract
- use WordPress.PHP.DontExtract
instead.WordPress.Variables.GlobalVariables
- use WordPress.WP.GlobalVariablesOverride
instead.WordPress.VIP.CronInterval
- use WordPress.WP.CronInterval
instead.WordPress.VIP.DirectDatabaseQuery
- use WordPress.DB.DirectDatabaseQuery
instead.WordPress.VIP.PluginMenuSlug
- use WordPress.Security.PluginMenuSlug
instead.WordPress.VIP.SlowDBQuery
- use WordPress.DB.SlowDBQuery
instead.WordPress.VIP.TimezoneChange
- use WordPress.WP.TimezoneChange
instead.WordPress.VIP.ValidatedSanitizedInput
- use WordPress.Security.ValidatedSanitizedInput
instead.WordPress.WP.PreparedSQL
- use WordPress.DB.PreparedSQL
instead.WordPress.XSS.EscapeOutput
- use WordPress.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 the WordPress.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.WordPress.DB.SlowDBQuery.DeprecatedWhitelistFlagFound
error code which is superseded by the blanket deprecation warning for using the now deprecated WPCS native whitelist comments.WordPress.PHP.TypeCasts.NonLowercaseFound
error code which has been replaced by the upstream Generic.PHP.LowerCaseType
sniff.WordPress.PHP.TypeCasts.LongBoolFound
and WordPress.PHP.TypeCasts.LongIntFound
error codes which has been replaced by the new upstream PSR12.Keywords.ShortFormTypeKeywords
sniff.WordPress.Security.EscapeOutput.OutputNotEscapedShortEcho
error code which was only ever used if WPCS was run on PHP 5.3 with the short_open_tag
ini directive set to off
.CSRF
Functions
Variables
VIP
XSS
WordPress.NamingConventions.ValidVariableName
: The customVariableWhitelist
property, which had been deprecated since WordPressCS 0.11.0. Use the customPropertiesWhitelist
property instead.WordPress.Security.EscapeOutput
: The customSanitizingFunctions
property, which had been deprecated since WordPressCS 0.5.0. Use the customEscapingFunctions
property instead.WordPress.Security.NonceVerification
: The errorForSuperGlobals
and warnForSuperGlobals
properties, which had been deprecated since WordPressCS 0.12.0.vip_powered_wpcom
function from the Sniff::$autoEscapedFunctions
list which is used by the WordPress.Security.EscapeOutput
sniff.AbstractVariableRestrictionsSniff
class, which was deprecated since WordPressCS 1.0.0.Sniff::has_html_open_tag()
utility method, which was deprecated since WordPressCS 1.0.0.$php_reserved_vars
property from the WordPress.NamingConventions.ValidVariableName
sniff in favour of using a PHPCS native property which is now available.@codingStandardsChangeSetting
annotation, which is generally only used in unit tests.PHP_CodeSniffer
< 3.3.1 was not fully compatible with PHP 7.3. Now the minimum required PHPCS has been upped to PHP_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.