Table of Contents
- What is Theme Check?
- Theme Check Architecture
- Common Theme Check Failures
- Custom Rules and Extensions
- CI/CD Integration
- Interpreting Theme Check Results
- Fixing Theme Violations
- FAQ
What is Theme Check?
WordPress Theme Check is an automated static analysis tool that scans WordPress themes against the WordPress Theme Review Team guidelines. The plugin examines theme code, templates, functions, CSS, and configuration to identify issues that could affect functionality, security, performance, or compliance. Rather than requiring human code review, Theme Check automates the detection of common problems.
The WordPress Theme Review Team maintains standards that all themes submitted to the WordPress.org theme directory must meet. These standards cover security (no unsafe PHP functions), functionality (proper use of WordPress hooks and APIs), accessibility (WCAG compliance), and internationalization (support for translations). Theme Check enforces these standards by scanning code for patterns that violate them.
When you run Theme Check on a theme, it analyzes:
- All PHP files for security issues
- Template files for proper WordPress API usage
- CSS for vendor prefixes and standards compliance
- Functions for deprecated WordPress functions
- Configuration for proper theme header comments
- Text strings for proper localization
- JavaScript for security issues
The tool outputs a report listing all issues found, categorized by severity (error, warning, recommendation). This report helps developers understand what changes are needed before submitting a theme to WordPress.org or before deploying a theme to production.
Theme Check is particularly valuable because it catches issues that might otherwise require extensive code review. A developer can run Theme Check during development and fix problems incrementally, rather than discovering issues at the end of development or during theme review. This saves time and ensures themes meet community standards.
The tool is extensible. Beyond the standard checks, developers can create custom rules specific to their organization's standards, their client's requirements, or specialized use cases. This makes Theme Check valuable not just for WordPress.org submissions but for internal theme quality management.
Theme Check Architecture
Understanding how Theme Check works helps you interpret results and create custom rules. The plugin consists of several components working together.
The checker class is the core engine. It loads theme files, analyzes them according to rules, and collects results. The checker reads theme code without executing it—this is static analysis, not dynamic testing. This approach is fast and safe; running untrusted code would be dangerous.
Rules are individual checks that scan for specific issues. WordPress provides about 80 built-in rules covering common problems. Each rule can look for:
- Specific function calls (e.g., searching for uses of
eval()which is unsafe) - Patterns in code (e.g., checking that all functions are properly prefixed)
- File structure (e.g., verifying required theme files exist)
- CSS properties (e.g., checking for proper vendor prefixes)
- Comments and metadata (e.g., validating theme header information)
When Theme Check runs, it applies all active rules to the theme and collects any violations each rule finds.
The file system scanner traverses the theme directory, reading all relevant files. For performance, it filters to PHP, CSS, and JavaScript files, ignoring images and other assets. The scanner identifies the theme structure and passes files to rules for analysis.
The results aggregator collects all violations from all rules, categorizes them by severity, and generates a report. The report shows each violation's location (file and line number), severity, and description.
The admin interface displays results in WordPress. Developers can click on violations to see exactly where the issue appears in their code. Many common issues include suggested fixes in the violation description.
Custom rule support allows extending Theme Check. Developers can create PHP classes implementing the ThemeCheck_Check interface, and Theme Check automatically discovers and runs them. This extensibility is key to making Theme Check useful beyond WordPress.org submissions.
Common Theme Check Failures
Certain violations appear repeatedly across themes. Understanding these common failures helps developers avoid them and fix them quickly.
Missing theme header is a fundamental failure. Every WordPress theme must have a style.css file with a header comment containing theme metadata:
/*
Theme Name: My Theme
Theme URI: https://example.com/my-theme
Description: A custom WordPress theme
Version: 1.0
Author: John Doe
Author URI: https://example.com
License: GPL v2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html
Text Domain: my-theme
Domain Path: /languages
*/
If this header is missing or incomplete, Theme Check fails the theme. The solution is simple: add the proper header. WP HealthKit helps identify missing or malformed theme headers during security audits.
Unsafe functions are functions that pose security risks. WordPress Theme Review forbids using:
eval(): Executes arbitrary PHP codeassert(): Can execute codecreate_function(): Creates functions dynamicallyextract(): Modifies variable scope in unexpected wayscall_user_func()with unsanitized input
If a theme uses any of these functions, Theme Check flags it. The solution usually involves rewriting the code to use safer alternatives. For example, instead of eval(), use filters or callbacks.
Escaping and sanitization violations occur when themes output data without proper WordPress escaping functions. Example violation:
// UNSAFE: outputs user data without escaping
echo $user_input;
// SAFE: uses WordPress escaping function
echo esc_html( $user_input );
Theme Check detects when code outputs variables without using esc_html(), esc_attr(), esc_url(), or similar functions. Fixing this requires adding appropriate escaping around all output.
Improper use of WordPress APIs happens when themes use outdated or incorrect WordPress functions. For example:
// WRONG: directly accessing global
global $wp_query;
$posts = $wp_query->posts;
// RIGHT: using WordPress function
$posts = get_posts();
Theme Check flags when themes should be using official WordPress functions instead of accessing internals. The solution is replacing the code with proper API calls.
Missing internationalization (i18n) occurs when text strings aren't wrapped in translation functions. Example:
// NOT translatable
echo "Welcome to my site";
// Translatable
echo __( "Welcome to my site", "my-theme" );
Every user-facing string should be wrapped in __(), _e(), esc_html__(), or similar functions with the theme's text domain. This allows translators to translate the theme into other languages. Fixing this requires finding all hardcoded strings and wrapping them properly.
Improper CSS vendor prefixes appear in stylesheets. Modern CSS doesn't require vendor prefixes, but if a theme uses them, Theme Check checks that they're complete:
/* INCOMPLETE: missing some vendor prefixes */
.box {
transform: rotate(45deg);
-webkit-transform: rotate(45deg);
}
/* COMPLETE: all necessary prefixes */
.box {
transform: rotate(45deg);
-webkit-transform: rotate(45deg);
-moz-transform: rotate(45deg);
-ms-transform: rotate(45deg);
}
Modern themes often don't need prefixes because browser support for unprefixed standards is broad. The solution is usually removing prefixes entirely rather than adding more.
Custom Rules and Extensions
Beyond built-in checks, Theme Check allows creating custom rules for organization-specific standards. This is valuable for enforcing internal coding standards or client requirements.
Creating a custom rule involves writing a PHP class implementing ThemeCheck_Check:
<?php
class MyCustomCheck implements ThemeCheck_Check {
/**
* Check name
*
* @return string
*/
public function get_name() {
return 'My Custom Check';
}
/**
* Check description
*
* @return string
*/
public function get_description() {
return 'Ensures all templates use proper hooks';
}
/**
* Check priority/severity
*
* @return integer
*/
public function get_priority() {
return 1;
}
/**
* Check if theme passes rule
*
* @return bool
*/
public function check() {
$check = true;
// Get all theme files
$files = $this->get_theme_files();
foreach ( $files as $file ) {
$content = file_get_contents( $file );
// Check for specific pattern
if ( preg_match( '/do_action.*hook_name/', $content ) ) {
// Hook found, continue
continue;
} else {
// Hook not found, fail
$this->error[] = array(
'file' => $file,
'message' => 'Missing custom hook',
);
$check = false;
}
}
return $check;
}
}
This custom check verifies that all theme files implement a specific action hook. You could extend this to check for:
- Specific function calls in templates
- Particular CSS classes or patterns
- Required configuration values
- Proper namespace usage
- Client-specific coding standards
Registering custom rules in Theme Check involves adding them to the checklist. Custom rules can be bundled with a theme, distributed as a separate plugin, or created dynamically based on configuration.
Organizations using custom rules can enforce standards across all themes:
- Required action hooks for WooCommerce integration
- Specific CSS naming conventions (BEM, SMACSS)
- Security practices beyond WordPress standards
- Performance standards (no synchronous scripts, optimized images)
- Client branding requirements
CI/CD Integration
Integrating Theme Check into continuous integration pipelines ensures themes are automatically checked every time code is committed. This catches violations early before they reach production.
GitHub Actions workflow for Theme Check:
name: Theme Check
on: [push, pull_request]
jobs:
theme-check:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v2
- name: Setup WordPress
uses: shivammathur/setup-wordpress@v1
with:
wp-version: latest
extensions: php-mysql
- name: Install Theme Check
run: |
wp plugin install theme-check --allow-root
wp plugin activate theme-check --allow-root
- name: Run Theme Check
run: |
wp theme-check my-theme --allow-root
This workflow runs every time code is pushed or a pull request is created. If Theme Check finds violations, the build fails and developers must fix them before merging.
GitLab CI example:
theme-check:
stage: test
image: wordpress:latest
script:
- apt-get update && apt-get install -y mysql-server
- service mysql start
- wp theme-check my-theme --allow-root
Jenkins pipeline example:
pipeline {
agent any
stages {
stage('Theme Check') {
steps {
sh 'wp theme-check my-theme --allow-root'
}
}
}
post {
always {
junit 'theme-check-results.xml'
}
}
}
WP-CLI integration makes Theme Check accessible from command line:
# Check a specific theme
wp theme-check my-theme
# Check all themes
wp theme list | awk '{print $1}' | xargs -I {} wp theme-check {}
# Generate XML report for CI systems
wp theme-check my-theme --format=xml > report.xml
Integrating Theme Check into CI ensures quality gates. Themes with critical violations cannot be deployed. This prevents security issues and compliance violations from reaching production.
Interpreting Theme Check Results
Theme Check outputs results in multiple formats. Understanding how to read and interpret them helps developers efficiently fix violations.
The WordPress admin interface shows violations organized by severity:
- Errors (Critical): Security issues or violations that will cause WordPress.org rejection. Must be fixed.
- Warnings (High): Likely issues that should be fixed. May cause problems on some sites.
- Recommendations (Medium): Best practices and improvements. Nice to fix but not critical.
- Informational: Messages about theme compliance status.
Each violation shows:
- The violation message explaining what's wrong
- The file containing the violation
- The line number where the issue appears
- Often, suggested fixes
When reading results, prioritize by severity. Fix all errors first, then warnings, then recommendations if time allows.
Some violations appear multiple times if the issue exists in multiple places. Fixing the underlying problem might resolve dozens of violations at once. For example, if many strings lack translation functions, adding translation function support throughout the theme fixes all those violations together.
Understanding false positives helps avoid unnecessary fixes. Theme Check sometimes flags code that's actually safe but matches a dangerous pattern. For example, if a theme uses a variable that happens to contain the string "eval", Theme Check might flag it as using the dangerous eval() function. Examining the actual code reveals it's not unsafe.
Fixing Theme Violations
A systematic approach to fixing Theme Check violations minimizes errors and prevents introducing new problems.
Organize by violation type. Rather than fixing violations as listed, group them by type:
- All escaping violations together
- All internationalization violations together
- All function call violations together
This approach is efficient because the same fix pattern applies to each group.
For escaping violations, identify all output and add appropriate escaping functions:
// Before: Missing escaping
<div class="site-title"><?php echo $site_title; ?></div>
// After: Proper escaping
<div class="site-title"><?php echo esc_html( $site_title ); ?></div>
For internationalization violations, find hardcoded strings and wrap them:
// Before: Not translatable
$message = "Welcome to our site";
// After: Translatable
$message = __( "Welcome to our site", "my-theme" );
For improper API usage, replace deprecated or unsafe functions:
// Before: Accessing global
global $wp_query;
$posts = $wp_query->posts;
// After: Using proper API
$posts = get_posts();
Test changes thoroughly. After fixing violations, test the theme in WordPress to ensure functionality still works correctly. Some fixes might affect how the theme displays or behaves.
WP HealthKit helps identify when themes have unresolved Theme Check violations. The platform alerts you to critical issues that should be addressed before deploying themes to production.
FAQ
What's the difference between errors, warnings, and recommendations?
Errors are critical violations that WordPress.org will reject or regulators might flag. Warnings are likely issues that should be fixed but might not break functionality. Recommendations are best practices and improvements. Fix errors immediately, warnings soon after, and recommendations if time allows.
Can I suppress specific Theme Check violations?
Some Theme Check violations can be suppressed with code comments, but this isn't recommended unless you've carefully verified the code is safe. Suppressing violations without understanding them defeats the purpose of automated checking. If you believe a violation is a false positive, verify the code is actually safe before suppressing.
Does Theme Check find security vulnerabilities?
Theme Check finds common security patterns and unsafe functions, but it doesn't perform comprehensive security analysis. It catches things like uses of eval() or unescaped output, but a theme passing Theme Check could still have security issues. WP HealthKit provides more comprehensive security auditing beyond Theme Check.
Can I use Theme Check for non-WordPress themes?
No, Theme Check is WordPress-specific. It checks for WordPress APIs, functions, and conventions. For other template systems, you'd need different static analysis tools.
Does Theme Check slow down my WordPress site?
Theme Check is only active in development. It's disabled on production sites, so it has no performance impact once deployed. However, running Theme Check can take a minute or two depending on theme size.
How do I update Theme Check to use newer rules?
Theme Check is updated through WordPress plugin updates. Keeping it current ensures you have the latest rules and checks. WordPress automatically updates it if you have auto-updates enabled.
Additional Resources
For a comprehensive view of how WP HealthKit approaches plugin analysis, explore our 62 verification layers or browse the plugin directory to see real audit scores. Ready to check your own plugin? Run a free audit now.
Frequently Asked Questions
How does WP HealthKit evaluate code quality in WordPress plugins?
WP HealthKit analyzes plugins across multiple quality dimensions including coding standards compliance, type safety, dependency health, error handling patterns, and documentation completeness. The tool provides actionable recommendations prioritized by impact, helping developers focus on the improvements that matter most.
What coding standards should WordPress plugins follow?
WordPress plugins should follow the WordPress Coding Standards enforced by PHPCS, which cover PHP, HTML, CSS, and JavaScript conventions. Beyond syntax, quality plugins also implement proper error handling, comprehensive input validation, consistent naming conventions, and thorough inline documentation.
How do I measure code quality improvements over time?
Track metrics like PHPCS violation counts, PHPStan error levels, test coverage percentages, and cyclomatic complexity scores across releases. Automated tools integrated into CI/CD pipelines provide trend data that shows quality trajectory and highlights areas needing attention.
What is technical debt and how do I manage it in WordPress plugins?
Technical debt represents the accumulated cost of shortcuts and deferred improvements in your codebase. Managing it requires regular identification through automated analysis, prioritization based on risk and impact, and systematic reduction as part of your development workflow rather than occasional cleanup sprints.
Why does code quality matter for WordPress plugin security?
Code quality and security are deeply interconnected. Well-structured code with clear separation of concerns makes vulnerabilities easier to identify and fix. Consistent coding patterns reduce the cognitive load during security reviews, and comprehensive error handling prevents information leakage that attackers exploit.
Conclusion
WordPress Theme Check automates the enforcement of WordPress theme standards, catching common security, functionality, and compliance issues before they reach production or become problems. By running Theme Check during development and integrating it into CI/CD pipelines, teams can ensure themes meet community standards and best practices.
Custom rules extend Theme Check to enforce organization-specific standards, making it valuable for internal theme development beyond WordPress.org submissions. Understanding common violations and fixing them systematically ensures high-quality themes that work reliably across different WordPress installations.
WP HealthKit complements Theme Check by providing broader security and compliance auditing. While Theme Check focuses on theme code patterns, WP HealthKit identifies runtime issues, plugin interactions, and compliance violations that static analysis alone cannot detect.
Audit your WordPress themes comprehensively with WP HealthKit to go beyond Theme Check and identify security, performance, and compliance issues in your complete WordPress installation.