Documentation for all the whitelist comments

[johnbillion]

It's difficult to determine which whitelist comments (eg. WPCS: sanitization ok) are available to use. These should be documented, and it would be good if the documentation recommended a standard format such as // WPCS: sanitization ok.

Here's the list I have. Are there more?

• Escaping: XSS
• Sanitising: sanitization
• Nonce verification: CSRF
• Loose comparison: loose comparison
• Overriding WordPress globals: override
• Use of superglobal: input var

[JDGrimes]

Previously: #361

[JDGrimes]

Related: #228

[westonruter]

Note also that I've proposed a way to standardize these whitelisting comments in a model following JSCS, as opposed to our current ad hoc system: squizlabs/PHP_CodeSniffer#604

Example:

echo $do_you_trust_me; // @codingStandardsIgnoreLine WordPress.XSS.EscapeOutput 

[JDGrimes]

Uses of ::has_whitelist_comment().

Uses of preg_match().

There are two more to add to your list from the direct database query sniff:

• Direct database query: db call
• Database query without caching: cache

The reason that these don't use ::has_whitelist_comment() is because they check for comments differently than the other sniffs did, so the transition would not have been backward compatible.

[JDGrimes]

Note also: there is a wiki, and you are welcome to contribute to it. 😄

[johnbillion]

Done! https://github.com/WordPress-Coding-Standards/WordPress-Coding-Standards/wiki/Whitelisting-code-which-flags-errors

[JDGrimes]

Thanks @johnbillion. I've added a section cautioning against overuse, and explaining how to refactor the example to actually fix it without adding the whitelisting flag.