Upgrade Guide to WordPressCS 2.0.0 for Developers of external standards

If you maintain an external PHPCS standard which has WordPressCS as a dependency, you may need to update your code to be compatible with WordPressCS 2.0.0. This guide is intended to help you do so.

Namespace change

The namespace used by WordPressCS has been changed from WordPress to WordPressCS\WordPress.

If you have sniffs in your standard which extend sniffs from WordPressCS, you will need to adjust the use statements or FQN references to the WordPressCS (abstract) sniffs.

Old:

use WordPress\Sniff;

class MyCustomSniff extends Sniff {}

New:

use WordPressCS\WordPress\Sniff;

class MyCustomSniff extends Sniff {}

The Sniff::$phpcsCommentTokens property has been removed

The property was only intended as a temporary workaround while WordPressCS still supported PHP_CodeSniffer < 3.2.3.

If you have sniffs which used this property, you will need to adjust them to use the PHPCS native property. Take note of the change from using the type array key to code.

Old:

use WordPress\Sniff;

class MyCustomSniff extends Sniff {
	public function process_token( $stackPtr ) {
		if ( isset( $this->phpcsCommentTokens[ $this->tokens[ $stackPtr ]['type'] ] ) ) {
			// Do something.
		}
	}
}

New:

use WordPress\Sniff;
use PHP_CodeSniffer\Util\Tokens;

class MyCustomSniff extends Sniff {
	public function process_token( $stackPtr ) {
		if ( isset( Tokens::$phpcsCommentTokens[ $this->tokens[ $stackPtr ]['code'] ] ) ) {
			// Do something.
		}
	}
}

Support for @codingStandardsChangeSetting has been removed

If you extended WordPressCS classes/methods in your standard and used the @codingStandardsChangeSetting annotation in your unit tests, your unit tests may now fail.

You need to update these type of annotations to use the PHPCS 3.2.0+ phpcs:set syntax and for array properties, the PHPCS 3.3.0+ array syntax for phpcs:set.

Refs:

• https://github.com/squizlabs/PHP_CodeSniffer/releases/tag/3.2.0
• https://github.com/squizlabs/PHP_CodeSniffer/releases/tag/3.3.0

Support for incorrectly passed array properties via the Sniff::merge_custom_array() method has been removed

If you relied on the WordPressCS\WordPress\Sniff::merge_custom_array() to handle array properties, including when these have been passed as a comma-delimited string without the type="array" attribute set, and you want to continue to support these incorrectly passed properties, you'll need to start pre-processing these yourself before passing them to the function.

Old:

use WordPress\Sniff;

class MyCustomSniff extends Sniff {
	public function process_token( $stackPtr ) {
		$this->property_name = $this->merge_custom_array( $this->property_name, array(), false );
	}
}

New:

use WordPress\Sniff;

class MyCustomSniff extends Sniff {
	public function process_token( $stackPtr ) {
		if ( is_string( $this->property_name ) ) {
			$this->property_name = array_filter( array_map( 'trim', explode( ',', $this->property_name ) ) );
		}
		$this->property_name = $this->merge_custom_array( $this->property_name, array(), false );
	}
}

PHPCSAliases file has been removed

If you relied on the WordPressCS PHPCSAliases file to provide cross-version PHPCS support in the form of class aliases or the WordPressCS native class autoloader, you'll now need to implement your own solution for this.

If you only support PHP_CodeSniffer > 3.1.0, neither the class aliases nor the WordPressCS native class autoloader should be needed.

Support for the WordPressCS native selective ignore comments is deprecated

The WordPressCS\WordPress\Sniff::has_whitelist_comment() method, which supported the WordPressCS native ignore comments, has been deprecated and will be removed in WordPressCS 3.0.0.

If any of your sniffs added ignore comments and relied on the WordPressCS WordPressCS\WordPress\Sniff::has_whitelist_comment() method to recognize these, you'll need to encourage your users to switch over to using the PHPCS native selective ignore annotations as introduced in PHP_CodeSniffer 3.2.0, or implement your own solution.

PHPCSHelper class

The WordPressCS\WordPress\PHPCSHelper class remains in place as a cross-version compatibility layer, though support for PHPCS 2.x has been removed from the file.

Upgrading to PHP_CodeSniffer 3.x

See the PHP_CodeSniffer Version 3 Upgrade Guide and the various changelogs for the PHPCS versions since, for more information.