When I started writing WordPress code, I formatted it however felt natural that day. Sometimes tabs, sometimes spaces. Sometimes Yoda conditions, usually not. Escaping when I remembered. It worked, but every time I came back to old code, or someone else read mine, it took longer than it should to understand. Adopting WordPress coding standards was the fix.
The WordPress Coding Standards changed that. They’re a published set of rules for formatting, naming, documentation and, importantly, security practices in WordPress PHP code. Combined with PHP_CodeSniffer, a tool that checks code against rules automatically, they turn “write cleaner code” from a vague intention into something you can measure and enforce.
What the standards cover
The WordPress Coding Standards, often shortened to WPCS, include several rule sets:
- WordPress-Core: formatting rules such as indentation with tabs, spacing inside parentheses, brace placement, naming conventions and Yoda conditions.
- WordPress-Docs: rules for inline documentation, like docblocks on functions and classes.
- WordPress-Extra: additional best practices, such as avoiding deprecated functions and discouraged patterns.
- WordPress: the complete set, combining all of the above.
The most valuable rules aren’t about formatting. They’re the security sniffs:
- Escaping output: flags variables echoed without esc_html, esc_attr, esc_url or similar.
- Input sanitisation: flags direct use of $_POST, $_GET and $_REQUEST without sanitising.
- Nonce verification: flags processing of form data without checking a nonce.
- Prepared SQL: flags database queries that interpolate variables instead of using $wpdb->prepare.
Those four checks alone catch a large proportion of the vulnerabilities reported in WordPress plugins every year.
Installing PHPCS and WPCS
The recommended way is through Composer, per project, so every developer and the CI server use the same versions.
In your plugin or theme folder:
The second package automatically registers the WordPress standards with PHPCS. Check they’re available:
You should see WordPress, WordPress-Core, WordPress-Docs and WordPress-Extra in the list.
Configuring a ruleset
Create a file called .phpcs.xml.dist in the project root. This tells PHPCS what to check and how:
The text domain rule checks that every translatable string uses your plugin’s text domain. The prefix rule checks that all global functions, classes, constants and hooks use your prefix, which prevents collisions with other plugins.
Running it
Check the whole project:
On an existing codebase, the first run is often alarming: hundreds or thousands of issues. Don’t panic. Most are formatting and can be fixed automatically.
PHPCBF, the code beautifier that comes with PHPCS, fixes everything it safely can: indentation, spacing, brace placement and similar. Run it, commit the result as a separate “coding standards formatting” commit, then look at what’s left.
What remains needs human attention: missing escaping, unsanitised input, missing nonces, unprepared queries, missing documentation and naming issues.
Dealing with legitimate exceptions
Sometimes the sniffs flag code that’s actually fine. For example, outputting HTML that was already escaped earlier, or reading a $_GET value only to compare it with a fixed string.
You can suppress a specific warning on a specific line with a comment, ideally with a reason:
Use this sparingly. Every ignore comment should be justified. If you find yourself ignoring the same rule everywhere, reconsider the code rather than the rule.
For whole categories you’ve decided not to follow, such as the file naming rule that some projects using PSR-4 autoloading don’t follow, exclude the rule in the ruleset instead:
Editor integration
Running PHPCS from the command line is fine, but seeing problems as you type is far better. Most code editors support it:
- VS Code: extensions like PHP Sniffer & Beautifier or phpcs use the project’s vendor/bin/phpcs and ruleset.
- PhpStorm: has built-in PHP_CodeSniffer support under Quality Tools.
- Sublime Text and Vim: plugins exist for both.
With editor integration, issues are underlined as you write, and you fix them before they’re ever committed.
Running checks automatically
Standards are only useful if they’re enforced. Two common approaches:
Pre-commit hooks
A Git pre-commit hook runs PHPCS on changed files before each commit. If there are errors, the commit is blocked. Tools like Husky or a simple script in .git/hooks make this easy. It’s fast because it only checks changed files.
Continuous integration
In GitHub Actions or another CI system, run PHPCS on every pull request:
| run: vendor/bin/phpcs –report=checkstyle | cs2pr</code> |
|---|
The cs2pr tool turns PHPCS output into annotations on the pull request, so issues appear directly next to the relevant lines.
Introducing standards to an existing codebase
If you’re adding PHPCS to a large, older project, requiring zero issues immediately isn’t realistic. Options:
- Fix automatically fixable issues first, in one big commit.
- Use a baseline. Some tools record existing issues and only fail on new ones.
- Check only changed files in CI, so new code must meet standards while old code is improved gradually.
- Prioritise security sniffs. Fix all escaping, sanitisation, nonce and SQL issues first, even if formatting issues remain.
Gradual improvement beats a big-bang rewrite that never gets finished.
Plugin Check and the WordPress.org review
If you publish plugins on WordPress.org, the review team uses automated checks based heavily on these standards, through the Plugin Check tool. Running PHPCS with WPCS before submitting catches most of the issues reviewers would raise, especially around escaping, sanitisation and prefixing. It shortens the review process noticeably.
The Plugin Check plugin itself is also worth running locally. It combines PHPCS-based checks with other tests specific to the plugin directory.
The real benefit
The visible benefit of coding standards is consistent formatting. The bigger benefit is that the security sniffs make you think about escaping and sanitisation every time you write output or handle input. After a few months, it becomes habit. You write esc_html without thinking, because the tool has reminded you a hundred times.
That habit is what prevents the next cross-site scripting vulnerability in your plugin. The formatting is a pleasant side effect.
A short tour of the most common findings
When I run PHPCS on a plugin for the first time, the same handful of issues usually make up most of the meaningful findings. Knowing them in advance makes the output less intimidating.
Output not escaped. Every echo of a variable without an escaping function is flagged. The fix is to escape late, at the point of output, with the function that matches the context: esc_html for text between tags, esc_attr for attribute values, esc_url for links and wp_kses_post for content that may contain safe HTML.
Input not sanitised or validated. Reading $_POST[’email’] and using it directly is flagged. Wrap it in wp_unslash and an appropriate sanitising function, and validate it before use.
Missing nonce verification. Any code that processes form submissions without checking a nonce is flagged. Add wp_nonce_field to the form and check_admin_referer or wp_verify_nonce when processing.
Direct database queries. Raw queries with variables inside them are flagged, as is direct database access without caching. Use $wpdb->prepare for any query with variables, and consider whether a WordPress API function would do the job instead.
Missing prefixes. Global functions, options, hooks and transients without your prefix are flagged. This prevents collisions with other plugins that might use the same names.
Translation issues. Strings without the correct text domain, or with variables inside translation functions, are flagged. Use placeholders with sprintf instead of concatenating variables into translatable strings.
Most of these take seconds to fix once you understand the pattern, and each one fixed is a small improvement in security or compatibility.
Getting a team to adopt it
Introducing coding standards to a team works best when it’s framed as a shared tool rather than a judgement. Start by agreeing on the ruleset together and documenting any exclusions with a short reason. Add editor integration for everyone, so problems are visible while writing rather than in review. Then turn on the CI check for new and changed files.
After a few weeks, code review conversations usually change. Instead of comments about spacing and brace placement, reviewers can focus on logic, architecture and user experience, because the tool handles the mechanical part. That shift alone makes the setup worthwhile for most teams.
Keep the tooling updated
WPCS gets new sniffs and fixes over time, so update it every few months with Composer. Review new warnings after each update, because they often reflect newly recognised security patterns worth adopting.
Frequently asked questions
Do I have to use tabs and Yoda conditions?
If you follow WordPress-Core, yes. Many agencies use their own variations for formatting but keep the security rules. What matters most is consistency within a project.
Does PHPCS slow down my site?
No. It’s a development tool that runs on your machine or CI server, not on the live site. Don’t deploy the vendor folder with development dependencies.
Can PHPCS check JavaScript and CSS?
PHPCS is for PHP. For JavaScript and CSS, use ESLint and Stylelint with the WordPress configurations provided by the @wordpress/scripts package.
Is passing PHPCS enough to make code secure?
No. It catches common mistakes, but it can’t understand your logic. Capability checks, authorisation and business rules still need careful thought and review.




