{"id":20854,"date":"2026-10-07T09:14:00","date_gmt":"2026-10-07T07:14:00","guid":{"rendered":"https:\/\/www.lukaswojcik.com\/blog\/?p=20854"},"modified":"2026-10-05T10:21:53","modified_gmt":"2026-10-05T08:21:53","slug":"plugin-check-ci","status":"publish","type":"post","link":"https:\/\/www.lukaswojcik.com\/blog\/en\/wordpress-plugins-tricks\/tutorials-en-wordpress-plugins-tricks\/plugin-check-ci\/","title":{"rendered":"Plugin Check locally and in CI: findings before the review"},"content":{"rendered":"
Every plugin submitted to the WordPress.org directory goes through an automated scan before a person from the Plugins Team reads the code. Several of the points that reviewers ask about can be detected mechanically: a missing license header, output that is not escaped, a script loaded from a public CDN, a text domain that does not match the slug. Plugin Check, short PCP, is the tool published by WordPress.org for this job. According to its description it runs most of the checks used for new submissions, on any WordPress installation and before anything is uploaded.<\/p>\n
This article shows Plugin Check 2.1.0 in three places: in the admin screen, on the command line with WP-CLI and in a GitHub Actions workflow built on the official action. A small plugin with deliberate mistakes serves as the test object. For each mistake the article names the check and the result code that a run of Plugin Check 2.1.0 on WordPress 7.1.2 reports, and then shows the corrected version.<\/p>\n
What Plugin Check examines<\/h2>\n
The current version in the directory is 2.1.0, released on 16 August 2026. It requires WordPress 6.3 and PHP 7.4; the plugin page lists \u201cTested up to\u201d 7.0.6, while the current WordPress release is 7.1.2. Version 2.1.0 added, among other things, a check for production-time changes to PHP error reporting.<\/p>\n
In the source of 2.1.0 the class Default_Check_Repository<\/code> registers 34 checks. Each check has a slug such as late_escaping<\/code> and belongs to one or more categories. Two kinds of checks exist. Static checks read the code without running it, mostly through PHP_CodeSniffer sniffs from the WordPress Coding Standards or from Plugin Check’s own sniff set, partly through custom logic. Runtime checks run the plugin, which has to be active, against a separate set of database tables and observe what it does; in 2.1.0 these are the five performance checks for script and style scope, script and style size, and loading strategy.<\/p>\n
\n\n
\n
Category (slug)<\/th>\n
Examples of checks in 2.1.0<\/th>\n<\/tr>\n<\/thead>\n
none: the category is defined, but no built-in check of 2.1.0 is assigned to it<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n
All security checks registered in 2.1.0 also carry the plugin_repo<\/code> category, so a run limited to Plugin Repo already covers escaping and direct file access. That matters because the plugin’s FAQ states that a plugin typically has to pass all checks in the Plugin Repo category to be approved for the directory. The other categories are described as additional.<\/p>\n
Every result is either an ERROR<\/code> or a WARNING<\/code> and carries a severity; the default is 5, a missing license in the plugin header is reported with 9. Errors mark violations of directory requirements. Warnings point to code that is often, but not always, a problem: reading $_GET<\/code> without a Nonce is fine for a harmless display parameter and a real hole in a form handler. The checks decide the type themselves, and the PHPCS ruleset of Plugin Check deliberately downgrades some sniffs, for example Nonce verification and input sanitization, to warnings.<\/p>\n
Running it locally: admin screen and WP-CLI<\/h2>\n
Plugin Check is installed like any other plugin. The project README advises against running it on a production site, because runtime checks execute the plugin under test. After activation, the screen under Tools \u2192 Plugin Check is available to users who can manage plugins. It offers a plugin selector plus checkboxes for categories and for result types. Results are grouped by file with line, column, type, code and message, and since version 1.8.0 they can be exported as CSV, JSON or Markdown.<\/p>\n
For repeated runs the WP-CLI command is more practical. The argument is a plugin slug, a path or the URL of a ZIP file. By default the command only executes static checks; runtime checks need the workaround documented in the README, where --require<\/code> loads the file cli.php<\/code> of Plugin Check before WordPress starts. In addition, the plugin under test has to be active; for an inactive plugin Plugin Check skips the runtime checks without a notice, and --checks=enqueued_scripts_scope<\/code> then ends with \u201cdoes not exist\u201d.<\/p>\n
# Install and activate Plugin Check (2.1.0 at the time of writing).\nwp plugin install plugin-check --activate\n\n# All static checks for wp-content\/plugins\/lw-hello-banner.\nwp plugin check lw-hello-banner\n\n# Include runtime checks (plugin must be active): load cli.php before WordPress boots.\nwp plugin check lw-hello-banner --require=.\/wp-content\/plugins\/plugin-check\/cli.php\n\n# Limit the run to categories or to single checks.\nwp plugin check lw-hello-banner --categories=plugin_repo,security\nwp plugin check lw-hello-banner --checks=late_escaping,i18n_usage\n\n# Errors only, as one JSON array for scripts.\nwp plugin check lw-hello-banner --ignore-warnings --format=strict-json\n\n# Show result codes, then ignore one specific code.\nwp plugin check lw-hello-banner --format=csv --fields=code,message\nwp plugin check lw-hello-banner --ignore-codes=textdomain_mismatch\n\n# Checks for an update of an existing directory plugin.\nwp plugin check lw-hello-banner --mode=update\n\n# What is available in the installed version.\nwp plugin list-checks --format=csv\nwp plugin list-check-categories<\/code><\/pre>\n
The most important flags of wp plugin check<\/code> in version 2.1.0:<\/p>\n
skip paths in file-based scans; .git<\/code>, vendor<\/code>, vendor_prefixed<\/code>, vendor-prefixed<\/code> and node_modules<\/code> are excluded by default<\/td>\n<\/tr>\n
show only results at or above a severity<\/td>\n<\/tr>\n
\n
--mode=<\/code><\/td>\n
new<\/code> (default) or update<\/code>; in update mode an outdated \u201cTested up to\u201d is reported as a warning instead of an error<\/td>\n<\/tr>\n
\n
--slug=<\/code><\/td>\n
override the slug used for text domain and readme comparisons<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n
Check slugs and result codes are two different things. --checks=i18n_usage<\/code> selects a check, --ignore-codes=WordPress.WP.I18n.TextDomainMismatch<\/code> hides a single finding from it. The CLI documentation recommends --format=csv --fields=code,message<\/code> to look up codes. One detail is relevant for scripts: in the 2.1.0 source the command prints its findings without setting an error exit status because of them. A shell script that is meant to fail therefore has to evaluate the output itself; in a test run against the faulty sample the command reported twelve errors and still ended with exit status 0. The GitHub Action does exactly that evaluation. With --format=json<\/code> each file gets a line FILE: \u2026<\/code> followed by its own JSON array, so the output as a whole is not valid JSON; --format=strict-json<\/code> returns a single array, but without file names. Without findings, both formats print only a success line.<\/p>\n
A sample plugin with built-in mistakes<\/h2>\n
The sample is a single file in the folder wp-content\/plugins\/lw-hello-banner\/<\/code>, so the slug is lw-hello-banner<\/code>. It prints a greeting at the top of the page, reads an optional name from the URL, offers a note field on Settings \u2192 General and loads a decorative script. It contains nine deliberate mistakes: no readme.txt<\/code>, no license header, a text domain that differs from the slug, no guard against direct file access, a call to error_reporting()<\/code>, register_setting()<\/code> without sanitization, output without escaping, a translatable string with a placeholder but without a translator comment, and a script loaded from a CDN without version and loading arguments.<\/p>\n
<?php\n\/**\n * Plugin Name: LW Hello Banner\n * Description: Shows a greeting banner at the top of the front page.\n * Version: 0.1.0\n * Author: Lukas Wojcik\n * Text Domain: hello-banner\n *\/\n\n\/\/ Intentionally faulty example for Plugin Check. Do not use on a live site.\n\nerror_reporting( E_ALL );\n\nfunction lw_hello_banner_register_setting() {\n\tregister_setting( 'general', 'lw_hello_banner_note' );\n\n\tadd_settings_field(\n\t\t'lw_hello_banner_note',\n\t\t__( 'Banner note', 'hello-banner' ),\n\t\t'lw_hello_banner_field',\n\t\t'general'\n\t);\n}\nadd_action( 'admin_init', 'lw_hello_banner_register_setting' );\n\nfunction lw_hello_banner_field() {\n\techo '<input type=\"text\" name=\"lw_hello_banner_note\" value=\"' . get_option( 'lw_hello_banner_note' ) . '\">';\n}\n\nfunction lw_hello_banner_assets() {\n\twp_enqueue_script( 'lw-hello-banner', 'https:\/\/cdn.jsdelivr.net\/npm\/canvas-confetti@1.9.3\/dist\/confetti.browser.min.js' );\n}\nadd_action( 'wp_enqueue_scripts', 'lw_hello_banner_assets' );\n\nfunction lw_hello_banner_render() {\n\t$name = isset( $_GET['lw_name'] ) ? $_GET['lw_name'] : 'Guest';\n\t$note = get_option( 'lw_hello_banner_note', '' );\n\n\techo '<div class=\"lw-hello-banner\"><p>' . sprintf( __( 'Hello, %s!', 'hello-banner' ), $name ) . ' ' . $note . '<\/p><\/div>';\n}\nadd_action( 'wp_body_open', 'lw_hello_banner_render' );<\/code><\/pre>\n
What Plugin Check reports for it<\/h2>\n
The following table lists the findings of wp plugin check lw-hello-banner<\/code> with Plugin Check 2.1.0 on WordPress 7.1.2, twelve errors and nine warnings in total; a run with --require<\/code> returns the same list. Line numbers are left out; OutputNotEscaped<\/code> appears four times, TextDomainMismatch<\/code> and NonceVerification.Recommended<\/code> twice each.<\/p>\n
$_GET['lw_name']<\/code> used raw<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n\nPlugin Check 2.1.0 sorts its checks into categories; errors fail the CI job, warnings are annotated<\/figcaption><\/figure>\n
Three observations from the table. First, the text domain is reported twice by different checks: the header check compares the Text Domain<\/code> header with the slug and issues a warning, while the i18n sniff compares every translation call with the slug and issues an error. Second, the Nonce and sanitization findings do not come from the Security category but from plugin_review_phpcs<\/code>, a PHPCS run with Plugin Check’s review ruleset; a run with --categories=security<\/code> would not show them. Third, the ruleset also contains the sniff group WordPress.PHP.DevelopmentFunctions<\/code> as a warning. It does report the error_reporting()<\/code> line a second time, as
![\"From](\"https:\/\/www.lukaswojcik.com\/blog\/wp-content\/uploads\/diagrams\/wp-plugin-check-en.png?v=20260930\")