Move sanitization methods to SanitizationHelperTrait + minor improvements

[jrfnl]

These methods haven't had extensive work done as they barely do any token walking themselves and the underlying functions used by the methods all have had work done to improve them.

Note: the is_only_sanitized() method could be moved to the NonceVerification sniff as it's only used by that sniff, but for now, I've elected to keep it together with the is_sanitized() method.

---

Rename SanitizingFunctionsTrait to SanitizationHelperTrait

The Sniff:;is_*sanitized() utility methods are about to be moved to this trait, but once they have been, the trait name is no longer correct as all other *Functions[Helper|Trait] classes/traits only deal with function lists and checking whether something is in those lists, while this trait will now do more than that.

With that in mind, I propose to rename the trait to SanitizationHelperTrait.

Move sanitization methods to SanitizationHelperTrait

This moves the last utility functions from the Sniff class to a dedicated trait.

I am also explicitly marking the trait as internal API to allow us to iterate on this (not so very clean) solution in future 3.x releases without being forced to wait for a 4.0 release.

The methods have been made stand-alone, as in, the presumption that the WPCS Sniff class is being extended has been removed by adding the $phpcsFile parameter.

Closes #1465

SanitizationHelperTrait::is_sanitized(): add some defensive coding

As this method is now stand-alone, we'd better make sure the token being examined exists.

Note: no need to do the same for the is_only_sanitized() method as the first thing that method calls is this method and if this method returns false, the is_only_sanitized() method will too.

SanitizationHelperTrait::is_sanitized(): implement PHPCSUtils

Note: The $functionPtr variable is overwritten a few lines later and the other variables being set are effectively unused (other than in these lines), so this code can be safely removed/replaced.

SanitizationHelperTrait::is_sanitized(): efficiency tweak - move unset check up

A variable which is being unset, doesn't need to be unslashed or sanitized, so bow out early.

SanitizationHelperTrait::is_sanitized(): efficiency fix/improve performance

Remove the need for a call to the performance negative array_diff_key() function by setting up the original arrays in a better way.

SanitizationHelperTrait::is_sanitized(): minor code tweaks

• Get rid of an unnecessary else.
• Improve readability of long condition.
• Get rid of unnecessary true/false condition code.

SanitizationHelperTrait::is_sanitized(): minor doc tweaks

[jrfnl]

Also note: I still have a niggly feeling there is a logic error in the is_only_sanitized() method, but I haven't been able to figure out the reason this was originally coded this way, so I'm not touching it for now.

The logic error I suspect is in the following code:

		// The only parentheses should belong to the sanitizing function. If there's
		// more than one set, this isn't *only* sanitization.
		return ( \count( $tokens[ $stackPtr ]['nested_parenthesis'] ) === 1 );

This seems to presume that parentheses could only be for function calls, while the extra parentheses may just as well be for control structure conditions.

If the other parentheses are for control structure conditions, I believe the variable should still count as "only sanitized".
It also discounts situations where unslashing is nested within a sanitization function call (which is taken into account in the NonceVerification sniff, but that is now inconsistent).

$a = is_email( $_GET['email'] ); // is_ony_sanitized(): true
$a = is_email( wp_unslash( $_GET['email'] ) ); // is_ony_sanitized(): false
if ( is_email( $_GET['email'] ) ) {} // is_ony_sanitized(): false

This should probably be further investigated when adding dedicated tests for these methods (#2272).

[jrfnl]

Repushed to fix the order of the remaining use import statements in the Sniff class. No other changes.

[dingo-d]

Left one comment, mostly as a reminder.