Skip to content

Upgrade Guide to WordPressCS 3.0.0 for ruleset maintainers

Jump to bottom Edit New page
Gary Jones edited this page Aug 20, 2023 · 2 revisions

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:

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.

Add a custom footer

IDE configuration

Fixing violations

Ignoring violations

Running in CI

For ruleset maintainers

For developers

Project History

Clone this wiki locally