Whitelisting code which flags errors

Sometimes, a block of code will be flagged by WPCS with an error which you wish to ignore. An example of this could be a variable which is sanitised or escaped elsewhere before being used or output.

WPCS lets you whitelist given errors for a line or block of code.

Example

The last line in the following block of code is safe, but will normally be flagged by WPCS for not being escaped on output.

function some_html() {
    return '<strong>bar</strong>';
}

$foo = some_html();

echo $foo; // WPCS: XSS ok.

A specially formatted inline comment has been appended to the line, stating that the line is "ok" and is not vulnerable to XSS. When this comment is in place, the error to which it refers will be ignored by WPCS.

The inline comment is in the format // WPCS: {flag} ok. The available flags are listed below.

Multiple flags can be combined in one comment like this:

function some_html() {
    return '<strong>bar</strong>';
}

$foo = some_html();

echo $foo; // WPCS: XSS ok, sanitization ok.

For multi-line statements, the inline comment should be placed at the end of the first line*:

printf( '%s', // WPCS: XSS ok.
    $foo
);

Available flags for whitelists

Escaping / XSS

// WPCS: XSS ok.

Sanitization

// WPCS: sanitization ok.

Nonce verification / CSRF

// WPCS: CSRF ok.

Loose comparison

// WPCS: loose comparison ok.

Overriding WordPress globals

// WPCS: override ok.

Unprepared SQL

// WPCS: unprepared SQL ok.

Use of superglobal

// WPCS: input var okay.

Direct database query*

// WPCS: db call ok.

Database query without caching*

// WPCS: cache ok.

Slow taxonomy queries

// WPCS: tax_query ok.

When to Use

These flags are provided for convenience, but using them should generally be avoided. Most of the time you can fix the error by either refactoring your code, or by updating the configuration of WPCS.

Using our example above, ideally we might refactor the code to be something like this:

function some_html() {
    echo '<strong>bar</strong>';
}

This not only pleases WPCS, but it also makes it easier for you to see that the output is safe when reviewing the code.

Another possibility would be a less drastic refactoring of the code, in combination with an improved configuration for WPCS. If the some_html() function's return value is always escaped, we could add it to the list of auto-escaped functions by adding this in our XML config file:

<rule ref="WordPress.XSS.EscapeOutput">
	<properties>
		<property name="customAutoEscapedFunctions" value="some_html" type="array" />
	</properties>
</rule>

Then, if we refactored the code like this, WPCS would know that the value was escaped, and would automatically suppress the error:

function some_html() {
    return '<strong>bar</strong>';
}

echo some_html();

There are cases where refactoring is impractical or impossible, but usually you can avoid littering your code with these flags by doing just a very little work. That way, you not only shut up WPCS, you also improve your code in the process!

---

* For historical reasons, the cache and db call flags cannot currently be used together, although each of them can be used along with any other flags. They also behave slightly different than other flags when used in multi-line statements: other flags need to come at the end of the first line of the statement, while these two are required to come after the ; on the last line instead.