Upgrade Guide to WordPressCS 3.0.0 for ruleset maintainers

Updating your installation to WordPressCS 3.0.0

Composer project-based install

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-dependencies

Composer global install

If 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-dependencies

Installs based on the old installation instructions

If 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.

Other types of installs

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.

Removing artifacts from old installation methods

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.

CI integration

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.

"Old-style"/WordPressCS native ignore annotations

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.

Ruleset and PHPCS ignore annotations

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.

Sniffs

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

Error codes

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.MissingBracketCloser
• WordPress.CodeAnalysis.AssignmentIn[Ternary]Condition.NonVariableAssignmentFound

Ruleset and custom properties

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.

Excluding a group of checks

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

CLI configuration options

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.

Other

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.