Whitelisting code which flags errors

Juliette edited this page Jun 29, 2018 · 23 revisions

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.

Note: In PHPCS 3.2 a new whitelisting comment format is being introduced, that can be used for all sniffs.

Example: // phpcs:ignore WordPress.Security.EscapeOutput.

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 typically in the format // WPCS: {flag} ok., though any prefix and suffix can be added to the {flag}. It must use the // comment format. 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
);

/*
 * However, as of WPCS 0.14.0, the comment can also be placed at the end of the statement:
 */
printf( '%s',
    $foo
); // WPCS: XSS ok.

Available flags for whitelists

Escaping / XSS

WPCS 2013-06-11 +

// WPCS: XSS ok.

Sanitization

WPCS 0.4.0+

// WPCS: sanitization ok.

Nonce verification / CSRF

WPCS 0.5.0+

// WPCS: CSRF ok.

Loose comparison

WPCS 0.4.0+

// WPCS: loose comparison ok.

Overriding WordPress globals

WPCS 0.3.0+

// WPCS: override ok.

Unprepared SQL

WPCS 0.8.0+

// WPCS: unprepared SQL ok.

Tip: before whitelisting a query, if you are passing user-supplied data through $wpdb->prepare() as part of the $query parameter, even if that data is properly escaped, you also need to check that it is does not make the query vulnerable to sprintf()-related SQLi attacks.

Use of superglobal

WPCS 0.3.0+

// WPCS: input var ok.

Direct database query*

WPCS 0.3.0+

// WPCS: db call ok.

Database query without caching*

WPCS 0.3.0+

// WPCS: cache ok.

Slow (taxonomy) queries

WPCS 0.12.0+

// WPCS: slow query ok.

This flag was originally called tax_query and introduced in WPCS 0.10.0. The tax_query whitelist flag has been deprecated as of WPCS 0.12.0 and is superseded by the slow query flag.

Non-prefixed function/class/variable/constant in the global namespace

WPCS 0.12.0+

// WPCS: prefix ok.

WordPress spelling

WPCS 0.12.0+

// WPCS: spelling ok.

Precision alignment

WPCS 0.14.0+

// WPCS: precision alignment ok.

PreparedSQL placeholders vs replacements

WPCS 0.14.0+

// WPCS: PreparedSQLPlaceholders replacement count 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.Security.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 like this as the other flags can: cache, db call ok. Instead, they have to be used together like this: cache ok, db call ok. (each must be immediately followed by ok). 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.

You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.