Abstracts: change $exclude property from string to array

[jrfnl]

The $exclude property which is included in most abstract sniffs and by extension in all sniffs which use these abstracts, used to expect a comma-delimited list.
This comma-delimited list was then exploded to an array from within the sniff.

In other words, in reality the sniff expected an array.

This has now been formalized. All $exclude properties now expect array input.

As outlined in #1368, this is not a BC-break as properties passed as a comma-delimited string will still be supported (for now). Support for this may be removed at some point in the future.

The upside of making this change is that users who use WPCS 3.3.0, can start using the new property array format in their custom rulesets which makes for a more easily readable ruleset.

• Update the wiki section about the exclude property in custom rulesets.

Fixes #1368

Testing this PR

Testing this PR is a little finicky as it needs to be done manually, so here are the steps to do so:

1 - Start by saving the below code to a temporary test file.

Test file content

<?php

// AbstractArrayAssignmentRestrictions
$args = array(
	'orderby' => 'rand', // Bad.
);

// AbstractFunctionRestrictions
parse_url( 'http://example.com/' ); // Warning.

$json = json_encode( $thing ); // Warning, use wp_json_encode instead.

file_get_contents(); // Warning.

readfile(); // Warning.
fopen(); // Warning.

// AbstractClassRestrictions
$a = new WP_User_Search;

// AbstractFunctionParameter
in_array( 1, array( '1', 1, true ) ); // Warning.
array_search( 1, $array, false ); // Warning.

// AbstractVariableRestrictions
$query = "SELECT * FROM $wpdb->usermeta"; // Error.
$wp_db->update( $wpdb->users, array( 'displayname' => 'Kanobe!' ), array( 'ID' => 1 ) ); // Error.

2 - Next, create a custom ruleset with the below content and save it to a file

Initial ruleset

<?xml version="1.0"?>
<ruleset name="TEST 1368">
	<description>TEST 1368</description>

	<autoload>/path/to/WordPress/PHPCSAliases.php</autoload>

	<!-- AbstractArrayAssignmentRestrictions -->
	<rule ref="WordPress.VIP.OrderByRand"/>

	<!-- AbstractFunctionRestrictions -->
	<rule ref="WordPress.WP.AlternativeFunctions"/>

	<!-- AbstractClassRestrictions -->
	<rule ref="WordPress.WP.DeprecatedClasses"/>

	<!-- AbstractFunctionParameter -->
	<rule ref="WordPress.PHP.StrictInArray"/>

	<!-- AbstractVariableRestrictions -->
	<rule ref="WordPress.VIP.RestrictedVariables"/>

</ruleset>

3 - Run phpcs ./test-file.php --standard=./test-ruleset.xml --report=full,source and verify the output

Source report output

PHP CODE SNIFFER VIOLATION SOURCE SUMMARY
--------------------------------------------------------------------------------
SOURCE                                                                     COUNT
--------------------------------------------------------------------------------
WordPress.VIP.RestrictedVariables.user_meta__wpdb__users                   1
WordPress.VIP.RestrictedVariables.user_meta__wpdb__usermeta                1
WordPress.PHP.StrictInArray.FoundNonStrictFalse                            1
WordPress.PHP.StrictInArray.MissingTrueStrict                              1
WordPress.WP.DeprecatedClasses._WP_User_SearchFound                        1
WordPress.WP.AlternativeFunctions.file_system_read_fopen                   1
WordPress.WP.AlternativeFunctions.file_system_read_readfile                1
WordPress.WP.AlternativeFunctions.file_system_read_file_get_contents       1
WordPress.WP.AlternativeFunctions.file_get_contents_file_get_contents      1
WordPress.WP.AlternativeFunctions.json_encode_json_encode                  1
WordPress.WP.AlternativeFunctions.parse_url_parse_url                      1
WordPress.VIP.OrderByRand.orderby_orderby                                  1
--------------------------------------------------------------------------------
A TOTAL OF 12 SNIFF VIOLATIONS WERE FOUND IN 12 SOURCES
--------------------------------------------------------------------------------

4 - Update the custom ruleset with "old-style" excludes

Ruleset with old-style excludes

<?xml version="1.0"?>
<ruleset name="TEST 1368">
	<description>TEST 1368</description>

	<autoload>/path/to/WordPress/PHPCSAliases.php</autoload>

	<!-- AbstractArrayAssignmentRestrictions -->
	<rule ref="WordPress.VIP.OrderByRand">
		<properties>
			<property name="exclude" value="orderby"/>
		</properties>
	</rule>

	<!-- AbstractFunctionRestrictions -->
	<rule ref="WordPress.WP.AlternativeFunctions">
		<properties>
			<property name="exclude" value="parse_url,json_encode,file_get_contents,file_system_read"/>
		</properties>
	</rule>

	<!-- AbstractClassRestrictions -->
	<rule ref="WordPress.WP.DeprecatedClasses">
		<properties>
			<property name="exclude" value="deprecated_classes"/>
		</properties>
	</rule>

	<!-- AbstractFunctionParameter -->
	<rule ref="WordPress.PHP.StrictInArray">
		<properties>
			<property name="exclude" value="strict"/>
		</properties>
	</rule>

	<!-- AbstractVariableRestrictions -->
	<rule ref="WordPress.VIP.RestrictedVariables">
		<properties>
			<property name="exclude" value="user_meta"/>
		</properties>
	</rule>
</ruleset>

5 - Run phpcs again and confirm no errors/warnings are displayed.
6 - Update the custom ruleset with "new-style" excludes

Ruleset with new-style excludes

<?xml version="1.0"?>
<ruleset name="TEST 1368">
	<description>TEST 1368</description>

	<autoload>/path/to/WordPress/PHPCSAliases.php</autoload>

	<!-- AbstractArrayAssignmentRestrictions -->
	<rule ref="WordPress.VIP.OrderByRand">
		<properties>
			<property name="exclude" type="array">
				<element value="orderby"/>
			</property>
		</properties>
	</rule>

	<!-- AbstractFunctionRestrictions -->
	<rule ref="WordPress.WP.AlternativeFunctions">
		<properties>
			<property name="exclude" type="array">
				<element value="parse_url"/>
				<element value="json_encode"/>
				<element value="file_get_contents"/>
				<element value="file_system_read"/>
			</property>
		</properties>
	</rule>

	<!-- AbstractClassRestrictions -->
	<rule ref="WordPress.WP.DeprecatedClasses">
		<properties>
			<property name="exclude" type="array">
				<element value="deprecated_classes"/>
			</property>
		</properties>
	</rule>

	<!-- AbstractFunctionParameter -->
	<rule ref="WordPress.PHP.StrictInArray">
		<properties>
			<property name="exclude" type="array">
				<element value="strict"/>
			</property>
		</properties>
	</rule>

	<!-- AbstractVariableRestrictions -->
	<rule ref="WordPress.VIP.RestrictedVariables">
		<properties>
			<property name="exclude" type="array">
				<element value="user_meta"/>
			</property>
		</properties>
	</rule>
</ruleset>

7 - Run phpcs again and confirm no errors/warnings are displayed.

[JDGrimes]

Have not tested it but it looks good to me.

[jrfnl]

FYI: wiki has been updated