README

A shareable PHP_CodeSniffer ruleset for WordPress plugin development, composing four upstream standards into one opinionated layer:

1. PSR-12 — the primary style guide (naming, formatting, braces, indentation).
2. WordPress (WPCS) — WordPress-Extra + WordPress-Docs for WordPress security, database, PHP, API, and documentation best practices.
3. WordPress VIP (VIPCS) — a small, curated, platform-agnostic subset of WordPressVIPMinimum security/correctness sniffs.
4. PHPCompatibilityWP — PHP cross-version compatibility aware of WordPress's own polyfills.

Precedence philosophy

PSR-12 → WordPress → WordPress VIP

PSR-12 wins wherever rules overlap — especially naming and code formatting. WordPress best-practice sniffs are layered on top, but every WordPress or VIP sniff that conflicts with PSR-12 (tabs vs spaces, brace placement, snake_case function/variable names, file naming, array alignment, …) is explicitly excluded in WPTechnixWordPress/ruleset.xml. The result: PSR-12 code style with WordPress-grade security/correctness checks.

Why only some WordPress VIP sniffs?

VIPCS (automattic/vipwpcs) is not a style guide — it is additive policy for the managed WordPress VIP hosting platform, layered on top of WPCS. Most of its sniffs assume the VIP runtime and become false positives on a self-hosted plugin because they:

• recommend VIP-only wrapper functions that don't exist elsewhere (wpcom_vip_file_get_contents, "uncached" get_posts / attachment_url_to_postid);
• encode VIP's Varnish/Batcache edge cache (ban setcookie, reading $_COOKIE / HTTP_USER_AGENT);
• encode VIP's filesystem & ops policy (no fwrite/unlink, 15-minute minimum cron, posts_per_page ≤ 100, no admin-bar removal).

The standard does not reference the entire WordPressVIPMinimum ruleset. Only sniffs with universal value are included.

VIP sniffs that ARE included

VIP sniffs that are intentionally excluded

File operations, cookie/$_SERVER restrictions, the "uncached function" family, remote-data caching, low cache-TTL, admin-bar removal, restricted hooks, VIP path-layout include rules, and VIP severity overrides for cron / posts_per_page. See the inline documentation in ruleset.xml for the complete list and the reason for each exclusion.

Extra quality sniffs

On top of the four upstream standards, the ruleset enables a small set of PSR-12-compatible correctness/clarity sniffs from PHPCSExtra (Universal/Modernize) and core PHPCS (Generic) — no extra dependency, and none of them affect whitespace or naming:

A few more opinionated sniffs (e.g. DisallowShortTernary, DisallowLonelyIf, error-level strict comparisons) are included commented-out in the ruleset for opt-in from your own phpcs.xml.

Installation

composer require --dev wptechnix/wp-coding-standards

This installs PHP_CodeSniffer, WPCS, VIPCS, PHPCompatibilityWP, PHPCSUtils, PHPCSExtra, and the dealerdirect/phpcodesniffer-composer-installer plugin, which auto-registers all standards.

Downstream requirement: Composer must be allowed to run the installer plugin. In your plugin's composer.json:

{
    "config": {
        "allow-plugins": {
            "dealerdirect/phpcodesniffer-composer-installer": true
        }
    }
}

Usage

Create a phpcs.xml.dist in your plugin. You only need to set the two project-specific values (prefixes and text_domain) — everything else is inherited.

<?xml version="1.0" ?>
<ruleset name="MyPlugin">
    <description>My WordPress plugin coding standards.</description>

    <!-- Option A (recommended): reference by registered standard name. -->
    <rule ref="WPTechnixWordPress" />

    <!-- Option B (equivalent): reference by path. -->
    <!-- <rule ref="./vendor/wptechnix/wp-coding-standards/WPTechnixWordPress/ruleset.xml" /> -->

    <rule ref="WordPress.NamingConventions.PrefixAllGlobals">
        <properties>
            <property name="prefixes" type="array">
                <element value="myplugin_" />
            </property>
        </properties>
    </rule>

    <rule ref="WordPress.WP.I18n">
        <properties>
            <property name="text_domain" type="array">
                <element value="my-plugin" />
            </property>
        </properties>
    </rule>
</ruleset>

Then run:

vendor/bin/phpcs --standard=phpcs.xml.dist
# or, using the registered standard name:
vendor/bin/phpcs --standard=WPTechnixWordPress

Development

Commit messages follow Conventional Commits and are validated by commitlint via a Husky commit-msg hook. After cloning:

composer install   # PHP toolchain + standards
npm install        # commitlint + husky hooks

See CONTRIBUTING.md for details.

License

MIT © WPTechnix