wp-coding-standards

WordPress Coding Standards (PHPCS + WPCS)

Model note: Setup and config steps are mechanical (haiku). Fixing sniff violations across many files works fine on haiku. Only reach for sonnet/opus when violations involve subtle logic (e.g. escaping inside complex SQL builders).

Configure and enforce the WordPress Coding Standards via PHP_CodeSniffer. WPCS is required for WP.org submission and is the canonical style guide for all WordPress PHP code.

When to use

• "Set up PHPCS for my plugin", "add WordPress coding standards", "configure phpcs.xml".
• "Fix sniff violations", "run phpcbf", "auto-fix coding standards".
• "Add PHPCS to GitHub Actions / CI".
• "Why is PHPCS flagging X?", "suppress a false-positive sniff".
• Pre-submission audit: "is my code style WP.org–compliant?"

Not for: PHPStan static analysis or type checking — use wp-phpstan-stubs. Security auditing beyond style issues — use wp-plugin-audit.

Method

1. Install

composer require --dev squizlabs/php_codesniffer wp-coding-standards/wpcs dealerdirect/phpcodesniffer-composer-installer

Current WPCS is 3.1 (July 2026) — requires PHP 7.4+ and PHP_CodeSniffer 3.9+. Leave the requirement unpinned (as above) or pin wp-coding-standards/wpcs:"^3.1"; the 3.x line recognizes pluggable functions and reserved post types through WP 6.4/6.5 and defaults minimum_supported_wp_version to 6.2.

dealerdirect/phpcodesniffer-composer-installer auto-registers WPCS paths so no manual --config-set is needed. Verify:

vendor/bin/phpcs -i
# should list: WordPress, WordPress-Core, WordPress-Docs, WordPress-Extra

2. Configure phpcs.xml.dist

Place at project root. This is the canonical config file (.dist allows local phpcs.xml override).

<?xml version="1.0"?>
<ruleset name="My Plugin">
    <description>WordPress Coding Standards for My Plugin</description>

    <!-- What to scan -->
    <file>.</file>
    <exclude-pattern>vendor/*</exclude-pattern>
    <exclude-pattern>node_modules/*</exclude-pattern>
    <exclude-pattern>build/*</exclude-pattern>
    <exclude-pattern>*.min.js</exclude-pattern>
    <exclude-pattern>*.min.css</exclude-pattern>
    <exclude-pattern>tests/bootstrap.php</exclude-pattern>

    <!-- PHP version target -->
    <config name="testVersion" value="7.4-"/>

    <!-- Ruleset -->
    <rule ref="WordPress-Extra">
        <!-- Suppress if you use short array syntax (WP allows it since WP 5.5) -->
        <!-- <exclude name="Generic.Arrays.DisallowShortArraySyntax"/> -->
    </rule>
    <rule ref="WordPress-Docs"/>

    <!-- Text domain for i18n sniffs -->
    <rule ref="WordPress.WP.I18n">
        <properties>
            <property name="text_domain" type="array" value="my-plugin"/>
        </properties>
    </rule>

    <!-- Minimum WP version for deprecated functions -->
    <rule ref="WordPress.WP.DeprecatedFunctions">
        <properties>
            <property name="minimum_supported_version" value="5.9"/>
        </properties>
    </rule>

    <!-- Prefix all globals -->
    <rule ref="WordPress.NamingConventions.PrefixAllGlobals">
        <properties>
            <property name="prefixes" type="array" value="my_plugin,MyPlugin"/>
        </properties>
    </rule>

    <!-- Show sniff codes in output (for targeted suppression) -->
    <arg value="ps"/>
    <arg name="extensions" value="php"/>
    <arg name="colors"/>
</ruleset>