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 that is sanitized or escaped elsewhere before being used or output.

PHPCS allows you to ignore specific 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 WordPressCS 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 WordPressCS.

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

You can discover the code for each error by using the -s CLI argument (e.g., phpcs index.php -s).

When to Use

These ignore annotations 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 WordPressCS.

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

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

This satisfies WordPressCS 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 WordPressCS 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, WordPressCS 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 ignore annotations by doing just a very little work. That way, you satisfy WordPressCS and improve your code in the process!

WordPressCS native ignore comments

PHP_CodeSniffer supports the selective // phpcs:ignore Stnd.Category.SniffName.ErrorCode syntax since version 3.2.0. Prior to that, you could only use ignore annotations which would ignore all errors and warnings on a line.

To mitigate that WordPressCS offered support for a number of WordPressCS native selective ignore comments.

Support for the WordPressCS native ignore comments was deprecated in WordPressCS 2.0.0 and support has been removed completely in WordPressCS 3.0.0.

Historical reference of the WordPressCS native ignore comments

Escaping / XSS WordPressCS 2013-06-11 +

// WPCS: XSS ok.

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

Sanitization WordPressCS 0.4.0+

// WPCS: sanitization ok.

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

Nonce verification / CSRF WordPressCS 0.5.0+

// WPCS: CSRF ok.

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

Loose comparison WordPressCS 0.4.0+

// WPCS: loose comparison ok.

Overriding WordPress globals WordPressCS 0.3.0+

// WPCS: override ok.

Unprepared SQL WordPressCS 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 WordPressCS 0.3.0+

// WPCS: input var ok.

Direct database query* WordPressCS 0.3.0+

// WPCS: db call ok.

Database query without caching* WordPressCS 0.3.0+

// WPCS: cache ok.

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

Slow (taxonomy) queries WordPressCS 0.12.0+

// WPCS: slow query ok.

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

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

// WPCS: prefix ok.

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

WordPress spelling WordPressCS 0.12.0+

// WPCS: spelling ok.

Precision alignment WordPressCS 0.14.0+

// WPCS: precision alignment ok.

PreparedSQL placeholders vs replacements WordPressCS 0.14.0+

// WPCS: PreparedSQLPlaceholders replacement count ok.

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

• 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.