WordPress Coding Standards: PHP_CodeSniffer rules for WordPress projects

What WordPressCS actually checks, and who it is for

The repository describes itself as a collection of PHP_CodeSniffer rules (sniffs) to validate code developed for WordPress, with the stated aim of ensuring code quality and adherence to the official WordPress Coding Standards. That is a narrow job done thoroughly: it is a static analyser for PHP source, not a linter for templates, not a JavaScript or CSS checker, and not a runtime tool. It reads files, tokenises them, and reports violations with a severity and a fixable flag.

The audience is equally narrow. If you maintain a plugin, a theme, or a patch against WordPress core, and your team has agreed to follow the published WordPress conventions, this is the tool that turns that agreement into something a build can fail on. If you are a solo developer who has never run PHP_CodeSniffer, the package still works, but you are adding a second tool (PHPCS itself) before you get any value out of the first.

One detail worth noticing in the README: the project states plainly that it needs funding, and links to a funding section. That is unusual to see at the top of a coding standards repository, and it is a fair signal about how the maintenance load is distributed across a small number of people.

How the sniffs, rulesets and Composer plugin fit together

WordPressCS does not ship its own scanner. It depends on PHP_CodeSniffer, which does the parsing and reporting, and contributes sniffs to it. The wiring between the two is handled by the Composer PHPCS plugin (dealerdirect/phpcodesniffer-composer-installer), which the README says registers the rulesets from WordPressCS and other external standards with PHP_CodeSniffer automatically. That is why the install instructions begin with an allow-plugins line: Composer will not run that installer unless you permit it.

The rulesets themselves are directories at the repository root: WordPress/, WordPress-Core/, WordPress-Docs/ and WordPress-Extra/. The README describes the project as a super-set of the sniffs the WordPress community may need, and says that using the WordPress standard gives you all the checks. The narrower names are subsets you pass to phpcs when you want less. WordPress-Core is described as the main ruleset for the WordPress core coding standards; the README excerpt does not spell out what WordPress-Docs and WordPress-Extra contain, so treat those names as selectors rather than as documented scopes until you check the ruleset files.

Because everything is registered through Composer, the standard name you pass on the command line (WordPress) is resolved from the installed vendor directory rather than from a path you configure by hand. That is the main architectural difference from the older setup, where the standards directory had to be pointed at explicitly.

Installing WordPressCS with Composer and running a first scan

Since WordPressCS 3.0.0, the README states that installation via Composer is the only supported type of installation. Run these two commands from the root of your project. The first permits the PHPCS Composer installer to run; without it Composer will block the plugin. The second pulls the package in as a development dependency at version 3.x.

composer config allow-plugins.dealerdirect/phpcodesniffer-composer-installer true
composer require --dev wp-coding-standards/wpcs:"^3.0"

If you would rather have phpcs available everywhere instead of per project, the README gives a global variant of the same two commands, using composer global config and composer global require. On Windows the resulting binary lives under the Composer vendor bin directory, and the README suggests adding that directory to your PATH so phpcs can be called as a global command.

With the package installed, point phpcs at your code and select the standard by name. The README gives this exact invocation for a project-local install:

vendor/bin/phpcs -ps . --standard=WordPress

The -p flag shows progress and -s shows the sniff name responsible for each message, which is what you want on a first run. You should expect a long list on an existing codebase, because WordPress is the complete set of checks rather than a starter subset. To narrow the scope, swap the standard name for WordPress-Core, WordPress-Docs or WordPress-Extra.

For a global install the README gives the equivalent path form, with %USER_DIRECTORY% standing in for your home directory:

%USER_DIRECTORY%/Composer/vendor/bin/phpcs -ps . --standard=WordPress

To move to a newer release later, the README documents composer update wp-coding-standards/wpcs --with-dependencies for a project-local install, and composer global update wp-coding-standards/wpcs --with-dependencies for a global one.

Requirements, upgrade friction and what the README leaves open

The minimum requirements are explicit: PHP 7.2 or higher, with the Filter, libxml, Tokenizer and XMLReader extensions enabled, plus Composer. The README also recommends iconv and Multibyte String for best results. The badge in the README states the project is tested on PHP 7.2 through 8.5, so the supported range is wide, but the floor of 7.2 matters if you are on a host that pins an older interpreter.

The upgrade path is where the documentation is thinnest. The README warns that if you are upgrading from an older WordPressCS version to 3.0.0, you should read the upgrade guide for ruleset maintainers and end-users first, and links to it on the project wiki. That warning exists because the 3.0.0 release changed how the standard is installed and registered. If you maintain a custom ruleset file (the repository ships a phpcs.xml.dist.sample at the root as a starting point), that is the file to re-check after a major upgrade, because sniff names and ruleset references can move between versions. The README does not document a rollback procedure for a bad upgrade, so plan on pinning the version in composer.json if you need one.

A second limitation is structural rather than technical: WordPressCS only covers PHP. The related searches around JavaScript and HTML coding standards point at a real gap. If your build touches block editor JavaScript or theme CSS, this package will not check it, and you should not read a clean phpcs run as evidence that the whole repository conforms.

Where WordPressCS is the wrong tool

The clearest case against it is a project that is not written against the WordPress Coding Standards in the first place. The sniffs encode a specific set of conventions; pointing them at a codebase that deliberately follows PSR-12 will produce a wall of violations that nobody intends to fix, and the resulting noise trains people to ignore the output. In that situation a PSR-12 ruleset for PHP_CodeSniffer is the right choice, and the difference in approach is exactly the difference in convention: PSR-12 governs naming, brace placement and line length for general PHP, while WordPressCS governs those plus WordPress-specific concerns such as the conventions for core functions and file structure.

A second case is a project that cannot take a Composer dependency. Because the README states that Composer is the only supported installation type as of 3.0.0, there is no documented path for a manually vendored copy, and the older instructions are gone. If your deployment process forbids dev dependencies or your environment has no Composer at all, this package is not the one to fight with.

A third case is a team that wants formatting fixed automatically. WordPressCS reports violations and marks some as fixable, and the README has a section on fixing errors or ignoring them plus tools shipped with the project, but the available documentation does not detail what those tools do. Do not assume a single command rewrites your codebase; verify against the tools section before promising that to anyone.

Subsets, custom rulesets and the recommended additions

Choosing a standard name is the first tuning step. WordPress is the full set; WordPress-Core is the main ruleset for the WordPress core coding standards; WordPress-Docs and WordPress-Extra are the other two directories shipped at the repository root. The README has a section on custom rulesets and a section on customizing sniff behavior, which is where you go when a single sniff is wrong for your project rather than the whole standard. The repository also carries a phpcs.xml.dist.sample, so the intended workflow is to copy that file, adjust the included standards and excluded paths, and commit it, rather than passing --standard on every invocation.

The README additionally lists recommended additional rulesets, meaning the project expects to sit alongside other PHPCS standards rather than replace them. That matters for how you read a failure: a violation attributed to a WordPressCS sniff is a WordPress convention issue, while one from another standard is a different policy, and the -s flag is what tells them apart in the output.

There is also an IDE path. The README has a section on using PHPCS and WordPressCS from within your IDE, and a separate section on running the code through WordPressCS automatically with continuous integration tools. Neither is described in enough detail in the README to give exact configuration, so treat those sections as the place to look rather than as something already covered here.

Maintenance, releases and licence

The repository is not archived, and the last push was on 2026-09-21, which is recent. The most recent releases listed are 3.4.1 on 2026-07-27, 3.4.0 on 2026-07-16 and 3.3.0 on 2025-11-25. The gap between 3.3.0 and 3.4.0 is roughly eight months, which suggests a cadence of occasional larger releases rather than continuous small ones, and the 3.4.0 to 3.4.1 patch two weeks later is consistent with a follow-up fix after a feature release.

The practical upgrade cost is low for most users: bump the constraint in composer.json and run the update command the README documents. The cost is higher if you maintain a shared ruleset, because that is the artifact the 3.0.0 upgrade guide is written for, and it is the artifact that breaks when sniff names change. The changelog (CHANGELOG.md at the repository root) is the file to read before a major bump; the README does not summarise breaking changes itself.

Licensing is straightforward on the surface: the project is MIT licensed, and the LICENSE file is at the repository root. That is permissive and compatible with the usual WordPress plugin and theme distribution models, but it says nothing about the licences of the code you run it against, and it is not legal advice. If you redistribute a modified copy of the sniffs, the MIT terms are what govern that redistribution.

Editorial conclusion

Adopt WordPressCS if you write PHP for plugins, themes or WordPress core and already have a Composer-managed PHPCS setup, because the sniffs encode the published WordPress Coding Standards and the WordPress, WordPress-Core, WordPress-Docs and WordPress-Extra rulesets let you pick the depth. Skip it if you are working in JavaScript or CSS and expecting those conventions to be enforced, or if you cannot add a Composer dependency to the project. Before rolling it out across a repository, run vendor/bin/phpcs -ps . --standard=WordPress on one directory and read the violation list, since the complete ruleset is a superset and the first run on an existing codebase is usually long.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. README
4. Releases
5. WordPress/WordPress-Coding-Standards on GitHub