Upgrade Guide to WordPressCS 3.0.0 for ruleset maintainers
If you were already using a Composer project-based install, upgrade WordPressCS by running:
composer remove --dev dealerdirect/phpcodesniffer-composer-installer higidi/composer-phpcodesniffer-standards-plugin squizlabs/PHP_codesniffer
composer config allow-plugins.dealerdirect/phpcodesniffer-composer-installer true
composer require --dev wp-coding-standards/wpcs:"^3.0.0" --update-with-dependenciesIf you were already using a Composer global install, upgrade WordPressCS by running:
composer global remove --dev dealerdirect/phpcodesniffer-composer-installer higidi/composer-phpcodesniffer-standards-plugin squizlabs/PHP_codesniffer
composer global config allow-plugins.dealerdirect/phpcodesniffer-composer-installer true
composer global require --dev wp-coding-standards/wpcs:"^3.0.0" --update-with-dependenciesIf you were using a Composer install which was created using the composer create-project command or had downloaded the release zip directly, please delete the directory in which you had WordPressCS installed and follow the new installation instructions in the Readme to install WordPressCS from scratch.
If you were using a stand-alone install of PHP_CodeSniffer, like a git clone, PHAR, or PEAR install, with which you had registered WordPressCS using the installed_paths command, we strongly recommend you use a Composer based install instead. While installing WordPressCS without Composer is still possible, no support will be given anymore for such installs.
Also, note that the master branch has been renamed to main.
If you have a <config name="installed_paths" value="/path/to/wpcs" /> directive in your [.]phpcs.xml[.dist] ruleset file, please remove it.
The Composer PHPCS plugin is now included by default and will take care of setting the installed paths for Composer based installs.
Along the same lines, if you had a Composer post-install-cmd (or similar) script which registered the installed_paths, please remove it as it will interfere/overwrite the installed paths which the Composer plugin sets.
You may need to re-run composer install after removing these artifacts.
If you had set up your CI integration based on the old example scripts, please change this to use a Composer based CI integration. Please see the Wiki for updated example scripts for both GitHub Actions as well as Travis.
The use of these was deprecated in WordPressCS 2.0.0 and if you still used them, a deprecation warning was thrown.
Support for these comments has now been completely removed. Please use the PHPCS native selective ignore annotations, like // phpcs:ignore ..., instead.
A number of sniffs/error codes have different names in WordPressCS 3.0.0. If you referred to any of these directly, either in your [.]phpcs.xml[.dist] ruleset file or in inline phpcs:ignore/disable/enable annotations, you will need to update the referenced name.
| Old name | New Name |
|---|---|
Generic.Arrays.DisallowShortArraySyntax |
Universal.Arrays.DisallowShortArraySyntax |
Generic.Files.EndFileNewline |
PSR2.Files.EndFileNewline |
Squiz.WhiteSpace.LanguageConstructSpacing |
Generic.WhiteSpace.LanguageConstructSpacing |
Squiz.WhiteSpace.ObjectOperatorSpacing |
WordPress.WhiteSpace.ObjectOperatorSpacing |
WordPress.Arrays.ArrayDeclarationSpacing |
WordPress.Arrays.ArrayDeclarationSpacing + NormalizedArrays.Arrays.ArrayBraceSpacing
|
WordPress.Arrays.CommaAfterArrayItem |
NormalizedArrays.Arrays.CommaAfterLast + Universal.WhiteSpace.CommaSpacing
|
WordPress.Classes.ClassInstantiation |
Functionality has been split across PSR12.Classes.ClassInstantiation, Universal.Classes.RequireAnonClassParentheses and Universal.WhiteSpace.AnonClassKeywordSpacing. Additionally, the PEAR.Functions.FunctionCallSignature sniff has been improved and will also take over part of what was previously handled by the WordPressCS native sniff. |
WordPress.CodeAnalysis.AssignmentInCondition |
Generic.CodeAnalysis.AssignmentInCondition + WordPress.CodeAnalysis.AssignmentInTernaryCondition
|
WordPress.CodeAnalysis.EmptyStatement |
Generic.CodeAnalysis.EmptyPHPStatement |
WordPress.PHP.DisallowShortTernary |
Universal.Operators.DisallowShortTernary |
WordPress.PHP.StrictComparisons |
Universal.Operators.StrictComparisons - Note: the new sniff contains a fixer, but this fixer is turned off by default. |
WordPress.WhiteSpace.DisallowInlineTabs |
Universal.WhiteSpace.DisallowInlineTabs |
WordPress.WhiteSpace.PrecisionAlignment |
Universal.WhiteSpace.PrecisionAlignment |
WordPress.WP.TimezoneChange |
Now contained within the WordPress.DateTime.RestrictedFunctions sniff |
Note: if a replaced sniff had customizable properties, the name of those properties may be different for the replacement sniff. Please refer to the documentation for guidance.
Documentation on customizable properties can be found:
- For WordPressCS (WordPress sniffs): https://github.com/WordPress/WordPress-Coding-Standards/wiki/Customizable-sniff-properties
- For PHP_CodeSniffer itself (Generic, PEAR, PSR1, PSR2, PSR12, Squiz sniffs): https://github.com/squizlabs/PHP_CodeSniffer/wiki/Customisable-Sniff-Properties
- For PHPCSExtra (Modernize, NormalizedArrays, Universal sniffs): https://github.com/phpcsstandards/phpcsextra#sniffs
| Old name | New Name |
|---|---|
WordPress.Arrays.ArrayDeclarationSpacing.SpaceAfterKeyword |
NormalizedArrays.Arrays.ArrayBraceSpacing.SpaceAfterKeyword |
WordPress.Arrays.ArrayDeclarationSpacing.SpaceInEmptyArray |
NormalizedArrays.Arrays.ArrayBraceSpacing.EmptyArraySpacing |
WordPress.Arrays.ArrayDeclarationSpacing.NoSpaceAfterArrayOpener |
NormalizedArrays.Arrays.ArrayBraceSpacing.SpaceAfterArrayOpenerSingleLine |
WordPress.Arrays.ArrayDeclarationSpacing.SpaceAfterArrayOpener |
NormalizedArrays.Arrays.ArrayBraceSpacing.SpaceAfterArrayOpenerSingleLine |
WordPress.Arrays.ArrayDeclarationSpacing.NoSpaceBeforeArrayCloser |
NormalizedArrays.Arrays.ArrayBraceSpacing.SpaceBeforeArrayCloserSingleLine |
WordPress.Arrays.ArrayDeclarationSpacing.SpaceBeforeArrayCloser |
NormalizedArrays.Arrays.ArrayBraceSpacing.SpaceBeforeArrayCloserSingleLine |
WordPress.Arrays.ArrayDeclarationSpacing.CloseBraceNewLine |
NormalizedArrays.Arrays.ArrayBraceSpacing.SpaceBeforeArrayCloserMultiLine |
WordPress.PHP.IniSet.*_Blacklisted |
WordPress.PHP.IniSet.*_Disallowed |
WordPress.WP.AlternativeFunctions.file_system_read_* |
WordPress.WP.AlternativeFunctions.file_system_operations_* |
In addition to that, the following error codes have been split:
| Error code | Notes |
|---|---|
WordPress.Arrays.ArrayKeySpacingRestrictions.NoSpacesAroundArrayKeys |
Remains the same array access/assignments with a key. For assignments without a key, a new SpacesBetweenBrackets error code is introduced. |
WordPress.Classes.ClassInstantiation.MissingParenthesis |
Remains the same for named classes. For the parentheses for anonymous class, the errorcode changes to Universal.Classes.RequireAnonClassParentheses.Missing. |
WordPress.WhiteSpace.ControlStructureSpacing.NoSpaceAfterStructureOpen |
Remains the same for control structures. For function declarations, the error has been replaced by the Squiz.Functions.MultiLineFunctionDeclaration.SpaceAfterFunction error code. |
WordPress.WhiteSpace.ControlStructureSpacing.NoSpaceBeforeOpenParenthesis/ExtraSpaceBeforeOpenParenthesis |
Remains the same for control structures. For function declarations, the error has been replaced by the Squiz.Functions.MultiLineFunctionDeclaration.SpaceBeforeOpenParen error code. |
WordPress.WhiteSpace.ControlStructureSpacing.NoSpaceAfterOpenParenthesis/ExtraSpaceAfterOpenParenthesis |
Remains the same for control structures. For function declarations, the error has been replaced by the Squiz.Functions.FunctionDeclarationArgumentSpacing.SpacingAfterOpen error code. |
WordPress.WhiteSpace.ControlStructureSpacing.NoSpaceBeforeCloseParenthesis/ExtraSpaceBeforeCloseParenthesis |
Remains the same for control structures. For function declarations, the error has been replaced by the Squiz.Functions.FunctionDeclarationArgumentSpacing.SpacingBeforeClose error code. |
WordPress.WhiteSpace.ControlStructureSpacing.NoSpaceAfterCloseParenthesis |
Remains the same for control structures. For function declarations, the error has been replaced, depending on the context, by either the Generic.Functions.OpeningFunctionBraceKernighanRitchie.SpaceBeforeBrace, the Squiz.Functions.MultiLineFunctionDeclaration.SpaceBeforeUse, or the PSR12.Functions.ReturnTypeDeclaration.SpaceBeforeColon error code. |
WordPress.WP.CapitalPDangit.Misspelled |
WordPress.WP.CapitalPDangit.MisspelledInText and WordPress.WP.CapitalPDangit.MisspelledInComment. The other error codes remain the same. |
WordPress.WP.I18n.NonSingularStringLiteralSingle |
Remains the same for I18n functions with a parameter named $single. For I18n functions where the parameter is named $singular, the error code changes to WordPress.WP.I18n.NonSingularStringLiteralSingular. |
.. and the following error codes have been removed:
WordPress.Arrays.ArrayKeySpacingRestrictions.MissingBracketCloserWordPress.CodeAnalysis.AssignmentIn[Ternary]Condition.NonVariableAssignmentFound
The following properties which can be set in a custom ruleset have been renamed.
| Sniff | Old property name | New property name |
|---|---|---|
WordPress.Files.Filename |
custom_test_class_whitelist |
custom_test_classes |
WordPress.NamingConventions.PrefixAllGlobals |
custom_test_class_whitelist |
custom_test_classes |
WordPress.NamingConventions.ValidVariableName |
customPropertiesWhitelist |
allowed_custom_properties |
WordPress.PHP.NoSilencedErrors |
use_default_whitelist |
usePHPFunctionsList |
WordPress.PHP.NoSilencedErrors |
custom_whitelist |
customAllowedFunctionsList |
WordPress.WP.AlternativeFunctions |
minimum_supported_version |
minimum_wp_version |
WordPress.WP.DeprecatedClasses |
minimum_supported_version |
minimum_wp_version |
WordPress.WP.DeprecatedFunctions |
minimum_supported_version |
minimum_wp_version |
WordPress.WP.DeprecatedParameters |
minimum_supported_version |
minimum_wp_version |
WordPress.WP.DeprecatedParameterValues |
minimum_supported_version |
minimum_wp_version |
WordPress.WP.GlobalVariablesOverride |
custom_test_class_whitelist |
custom_test_classes |
If you use any of these properties, you will need to update your ruleset to use the new name instead. Yes, two of them are intentionally in camel case.
Additionally, the following properties have been removed:
| Sniff | Property name | Alternative |
|---|---|---|
WordPress.WhiteSpace.ControlStructureSpacing |
spaces_before_closure_open_paren |
This is now checked via a different sniff and is no longer configurable. Closures are now expected to have exactly one space between the function keyword and the open parenthesis. |
WordPress.WP.I18n |
check_translator_comments |
Exclude the WordPress.WP.I18n.MissingTranslatorsComment and the WordPress.WP.I18n.TranslatorsCommentWrongStyle error codes instead. |
Some sniffs allow for excluding a group of checks via the exclude property.
The following group name has changed:
| Sniff | Old group name | New group name |
|---|---|---|
WordPress.WP.AlternativeFunctions |
file_system_read |
file_system_operations |
The minimum_supported_wp_version config setting, which can be set at runtime by using --runtime-set setting_name setting_value or by adding <config name="setting_name" value="setting_value"/> in a ruleset, has been renamed to minimum_wp_version.
Please read the changelog carefully before upgrading.
This release contains lots of bugfixes, so if you'd previously ignored certain issues, either from the ruleset or using the PHPCS selective ignore annotations, because of bugs in sniffs, please review your ignore annotations using the --ignore-annotations CLI option and/or re-enable those sniffs.