Ignoring Parts of a File

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

PHPCS lets you whitelist given errors for a line or block of code. See: https://github.com/squizlabs/PHP_CodeSniffer/wiki/Advanced-Usage#ignoring-parts-of-a-file

Example:

The last line in the following code block 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; // phpcs:ignore WordPress.Security.EscapeOutput.OutputNotEscaped

A specially formatted inline comment has been appended to the line, stating that PHPCS should ignore the line. When this comment is in place, the error to which it refers will be ignored by WPCS.

Combining Ignore Comments

Multiple violation codes can be combined in one comment like this:

echo $foo; // phpcs:ignore WordPress.Security.EscapeOutput.OutputNotEscaped,Generic.Files.EndFileNewline.NotFound

As a side note, you can get to know the code for each error by using the -s CLI argument (e.g., phpcs index.php -s).

Deprecated: Available flags for WPCS whitelists

Note that WPCS had native whitelist comments like below:

// Input var okay.
or
// WPCS: Input var okay.

These have been deprecated in WPCS 2.0.0 and will be removed in WPCS 3.0.0. The PHPCS format (// phpcs:ignore) is the preferred format.

Escaping / XSS WPCS 2013-06-11 +

// WPCS: XSS ok.

(Equivalent to // phpcs:ignore WordPress.Security.EscapeOutput.OutputNotEscaped)

Sanitization WPCS 0.4.0+

// WPCS: sanitization ok.

(Equivalent to // phpcs:ignore WordPress.Security.ValidatedSanitizedInput.InputNotSanitized)

Nonce verification / CSRF WPCS 0.5.0+

// WPCS: CSRF ok.

(Equivalent to // phpcs:ignore WordPress.Security.NonceVerification)

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 does not make the query vulnerable to sprintf()-related SQLi attacks.

(Equivalent to // phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared)

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.

(Equivalent to // phpcs:ignore WordPress.DB.DirectDatabaseQuery.NoCaching)

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.

(Equivalent to // phpcs:ignore WordPress.NamingConventions.PrefixAllGlobals)

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.

(Equivalent to // phpcs:ignore WordPress.DB.PreparedSQLPlaceholders.UnfinishedPrepare)

When to Use

These comments 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 satisfies WPCS and 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, combined with an improved WPCS configuration. 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" type="array">
			<element value="some_html"/>
		</property>
	</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 satisfy WPCS and 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 must be used together: cache ok, db call ok. (each must be immediately followed by ok). They also behave slightly differently than other flags when used in multi-line statements: other flags need to come at the end of the statement's first line, while these two are required to come after the ; on the last line instead.