Wp Plugin Standards

WordPress Plugin Standards

Companion to wp-plugin-development. Apply this skill when a plugin must pass WordPress.org Plugin Check (PCP), or when improving code quality, documentation, or submission readiness.

When to use this skill

• Writing or modifying WordPress plugin PHP files
• Preparing a plugin for WordPress.org submission
• Reviewing plugin code for security, quality, or standards compliance
• Any task where plugin code reuse, documentation, or versioning is involved

Mandatory workflow

Step 0 is always required and may never be skipped. Do not modify any file until the user explicitly confirms they want to proceed after reviewing the report.

Step 0 — Review report (always first)

Before scanning files, derive the expected WordPress.org slug: Take the Plugin Name: header value, lowercase it, replace spaces with hyphens, and strip special characters. This is the expected Text Domain: value. If the plugin header Text Domain: does not match this derived slug, flag it as Critical immediately — this generates 70+ errors in PCP. Example: "CloudScale Free Backup and Restore" → cloudscale-free-backup-and-restore.

Then review against the 18 Detailed Plugin Guidelines (references/wordpress-org-guidelines.md) — these are the human-reviewer policy rules that Plugin Check does not catch and that cause most repeat rejections of otherwise-clean code. Explicitly check: trialware / locked features (G5), tracking without explicit opt-in (G7), "Powered by"/credit links not opt-in (G10), admin-notice hijacking (G11), bundling libraries WordPress ships (G13), third-party CDN / admin iframes / external code loading (G8), obfuscated or minified-only code (G4), GPL-incompatible bundled assets (G1), and readme spam (G12). Run the audit greps in that reference file.

Scan all plugin files and produce a findings report grouped by severity before doing anything else. Use this exact format:

WordPress Plugin Standards — Review

Critical — blocks WordPress.org submission

• file.php:123 Description of violation

High — security or data integrity risk

• file.php:78 Description of violation

Medium — code quality, documentation, reuse

• file.php:12 Description of violation

Low — style, naming, minor standards

• file.php:34 Description of violation

Passed

• Areas with no violations found

X critical · X high · X medium · X low issues found. Confirm to proceed with all fixes, or specify which severity levels to address.

Severity definitions:

Do not proceed to Step 1 until the user replies with confirmation.

Step 0.5 — Mandatory mechanical grep audit

Run these bash commands immediately after receiving confirmation. Do not skip. These greps catch violations that LLM file-reading routinely misses — they are deterministic and must always run before any file edits.

# 1. i18n domain passed as variable (NonSingularStringLiteralDomain) — one Critical per call
grep -rn "__(\|_e(\|esc_html__(\|esc_attr__(\|_x(\|_n(\|esc_html_e(\|esc_attr_e(\|esc_html_x(\|esc_attr_x(" --include=*.php . | grep '\$[a-zA-Z_]' | grep -v "vendor/\|node_modules/"

# 2. cURL usage — hard rejection
grep -rn "curl_init\|curl_exec\|curl_multi_init\|curl_share_init\|curl_file_create" --include=*.php . | grep -v "vendor/\|node_modules/"

# 3. Shell execution — hard rejection
grep -rn "\bshell_exec\b\|\bexec(\|\bsystem(\|\bpassthru(\|\bproc_open\|\bpopen(" --include=*.php . | grep -v "vendor/\|node_modules/"

# 4. _e() / _ex() unescaped output
grep -rn "\b_e(\|\b_ex(" --include=*.php . | grep -v "vendor/\|node_modules/"

# 5. Short tags
grep -rn "<?[^p]" --include=*.php . | grep -v "vendor/\|node_modules/"

# 6. application_detected — tooling files in zip
find . -maxdepth 3 \( -name "phpcs.xml*" -o -name ".phpcs.xml*" -o -name "phpunit.xml*" -o -name "package.json" -o -name "composer.json" -o -name "Gruntfile.js" -o -name "webpack.config.js" \) | grep -v "vendor/"

# 7. OutputNotEscaped — echo/print with unescaped $variables
# Lines containing echo/print AND a $variable but NO escaping function on the same line.
# False-negative caveat: a line like `echo esc_html($a) . $b` has esc_ so it won't appear here —
# read any line with multiple concatenated variables carefully even if it passes this filter.
grep -rn "\becho\b\|\bprint\b\|\bprintf\b\|<?" --include=*.php . \
  | grep '\$[a-zA-Z_]' \
  | grep -v 'esc_html\|esc_attr\|esc_url\|esc_js\|esc_textarea\|esc_sql\|esc_xml\|wp_kses\|absint\|intval\|number_format\|wp_json_encode\|sanitize_\|true\|false\|count(\|strlen(' \
  | grep -v "vendor/\|node_modules/\|//\s*phpcs:ignore"

# 8. parse_url — must use wp_parse_url() (WordPress.WP.AlternativeFunctions.parse_url_parse_url)
grep -rn "\bparse_url\s*(" --include=*.php . | grep -v "vendor/\|node_modules/"

# 9. InputNotSanitized — raw superglobal access; each hit must be sanitized via wp_unslash + sanitize_*
grep -rn "\$_POST\b\|\$_GET\b\|\$_REQUEST\b\|\$_COOKIE\b\|\$_SERVER\b" --include=*.php . \
  | grep -v "vendor/\|node_modules/\|//\s*phpcs:ignore" \
  | grep -v "wp_unslash\|sanitize_\|absint\|intval\|check_ajax_referer\|wp_verify_nonce\|check_admin_referer"

# 10. NonPrefixedClassFound — all class/interface/trait declarations; verify each starts with plugin prefix
grep -rn "^class \|^abstract class \|^final class \|^interface \|^trait " --include=*.php . \
  | grep -v "vendor/\|node_modules/"

Report every hit as a Critical finding before proceeding to Step 1.

Note on grep #7 (OutputNotEscaped): This grep surfaces most violations but can miss a line that has both an escaped variable and an unescaped one (e.g. echo esc_html($a) . $b). After running the grep, also read every PHP file section that outputs HTML and confirm every interpolated or concatenated $variable is wrapped in esc_html(), esc_attr(), esc_url(), esc_js(), or absint() at the point of output — not just earlier in the function.

Note on grep #9 (InputNotSanitized): This grep surfaces superglobal reads for review; lines that only check isset( $_POST['key'] ) without using the value are usually fine. Validate that every line where the value is used wraps it as sanitize_text_field( wp_unslash( $_POST['key'] ) ) or equivalent.

Step 1 — Check Utils

Before writing any new function, read includes/class-SLUG-utils.php and confirm the helper does not already exist there (see references/reuse.md).

Step 2 — Apply fixes

Apply fixes for the severity levels the user confirmed. Use references/security.md, references/cyber-security.md, references/coding-standards.md, references/performance.md, and references/accessibility.md as you go.

Step 3 — PCP checklist

Step through references/pcp-checklist.md and confirm zero remaining violations in the addressed categories.

Step 4 — Bump versions

Update plugin header Version:, VERSION constant, and readme.txt Stable tag: in one operation — all three must always match.

Step 5 — Update CHANGELOG.md

Add a dated entry for every change made (see references/reuse.md §3).

Required file structure

plugin-slug/
├── plugin-slug.php                    Main file — plugin header + VERSION constant
├── readme.txt                         WordPress.org readme
├── CHANGELOG.md                       Keep a Changelog format
├── uninstall.php                      Removes all plugin data on uninstall
├── includes/
│   ├── class-plugin-slug.php          Core plugin class
│   └── class-plugin-slug-utils.php   Shared helpers — single source of truth
├── admin/
│   ├── class-plugin-slug-admin.php
│   └── partials/
├── public/
│   ├── class-plugin-slug-public.php
│   └── partials/
└── assets/
    ├── css/
    └── js/

Non-negotiable rules

These apply to every file, every task. No exceptions.

Security

• Verify a nonce before processing any form, AJAX handler, or REST endpoint
• Sanitise all superglobal input on the way in; escape all output on the way out
• Use $wpdb->prepare() for every dynamic DB query — no interpolated SQL ever
• Gate every privileged action with current_user_can()

Code reuse

• Shared helpers live in class-SLUG-utils.php only — never duplicated across files
• Check Utils before writing any new function; if it exists there, call it

Documentation

• Every file, class, method, and function gets a full DocBlock (@since, @param, @return)
• Inline comments explain the why, not the what

Version tracking

• Plugin header Version:, VERSION constant, and readme.txt Stable tag: must always match
• CHANGELOG.md updated on every commit that changes behaviour

PCP compliance

• No echoed <script> or <style> tags anywhere — the top WordPress.org rejection reason

• No hidden files (filenames beginning with .) in the plugin directory — WordPress.org automated scan rejects them with hidden_files error. Common culprits: .distignore, .gitignore, .DS_Store. Exclude all dot-files from the distribution zip.

• No error_log(), var_dump(), print_r(), or bare die() in committed code

• No hardcoded URLs — use plugin_dir_url() and plugin_dir_path()

• Text domain must match the WordPress.org plugin slug — the slug is derived from the plugin name, not the folder name (e.g. "My Cool Plugin" → my-cool-plugin). PCP reports textdomain_mismatch and WordPress.WP.I18n.TextDomainMismatch on every i18n call if wrong. Always verify: slugify the plugin name and confirm it matches Text Domain: in the header.

• All enqueued assets versioned with the plugin version constant

• WordPress.org Contributors: field must contain the exact WordPress.org login username of the plugin owner/submitter — not a brand name, company slug, or display name (e.g. andrewjbaker, not cloudscale). The automated pre-reviewer warns if the submitting account's username is absent.

• All URLs in readme.txt must return HTTP 200 — Plugin URI, Author URI, and every link in == External services == (Terms, Privacy Policy) are validated by the automated pre-reviewer before human review; 404s block submission. Verify with curl -sI <url> | head -1 before submitting.

• Code comments must not contain external domain names — the automated pre-reviewer scans all file content (not just string literals) for URL-like patterns. A PHP doc comment such as * (as listed at cloudflare.com/ips-v4) is flagged as "Calling files remotely" even though no request is made. Remove or rewrite domain references in comments to avoid URL patterns (e.g. // see the Cloudflare IP range documentation instead of // cloudflare.com/ips-v4).

• No date() — use gmdate() (UTC) or wp_date() (localised). PCP flags WordPress.DateTime.RestrictedFunctions.date_date as an error on every date() call.

• No unlink() — use wp_delete_file(). PCP flags WordPress.WP.AlternativeFunctions.unlink_unlink.

• No rmdir() or readfile() — use WP Filesystem API. PCP flags these as errors.

• wp_die() must receive escaped strings — wp_die( esc_html__( 'Forbidden', 'slug' ) ) not wp_die( 'Forbidden' ). PCP flags EscapeOutput.OutputNotEscaped.

• Every echoed variable must be escaped — including intermediate variables that only hold safe values (e.g. 'checked', hex colours, pre-computed CSS class strings). PCP's EscapeOutput.OutputNotEscaped fires on any unescaped variable. No exceptions. Specific context rule: variables echoed inside onclick="..." attributes must use esc_js(), not esc_attr(). A variable already sanitised earlier (e.g. $row_ami_id = esc_attr(...)) still triggers the error if re-echoed without wrapping — always escape at the point of output.

• wp_unslash() required before every sanitize_*() on superglobal input — sanitize_text_field( wp_unslash( $_POST['field'] ?? '' ) ). PCP flags MissingUnslash otherwise.

• InputNotSanitized — PCP flags $_POST array values even when they are validated via array_map('intval', ...) or array_intersect() against a whitelist. Add // phpcs:ignore WordPress.Security.ValidatedSanitizedInput.InputNotSanitized -- sanitised via [method] on those lines.

• set_time_limit() with non-zero values (e.g. set_time_limit(120)) also triggers Squiz.PHP.DiscouragedFunctions — the suppress pattern applies to all values, not just set_time_limit(0).

• Schema queries (SHOW CREATE TABLE, DESCRIBE) require WordPress.DB.DirectDatabaseQuery.SchemaChange in addition to DirectQuery and NoCaching in the phpcs:ignore list.

• Multi-line $wpdb->prepare() calls — when a phpcs:ignore comment sits on the line above a multi-line statement, it only suppresses the first line. Use phpcs:disable / phpcs:enable blocks to cover all lines of multi-line DB calls containing interpolated table names.

• readme.txt: max 5 tags, max 150-char short description — PCP flags both violations.

• readme.txt == Description == max 2,500 words — the WordPress.org importer runs the Description through wp_trim_words() (whitespace word split) and truncates anything past 2,500 words on import, surfacing the warning "The Description section is too long and was truncated. A maximum of 2,500 words is supported." to authors/committers only. Truncated content is dropped from the public listing with no error to end users. Count with a whitespace split (matches wp_trim_words), not str_word_count() (which under-counts). Keep the section comfortably under the limit (target ≤ 2,400 words) and move overflow into other readme sections (FAQ, screenshots) or onto the help site. Audit: awk '/^==[[:space:]]*Description[[:space:]]*==/{f=1;next} /^==[[:space:]]/{f=0} f' readme.txt | wc -w — flag Critical if the result exceeds 2,500.

• Direct cURL (curl_init, curl_exec, etc.) in plugin-authored code is a hard WordPress.org rejection — identical treatment to shell_exec(). phpcs:ignore suppression silences PHPCS/PCP but human reviewers will still reject it. Every curl_exec call in your own code must be replaced with wp_remote_get() / wp_remote_post(). Third-party vendor libraries containing cURL are permitted — reviewers explicitly distinguish vendor code from plugin-specific code. The sole technically defensible exception in own code is a sub-second connect timeout requirement (e.g. AWS IMDS polling) where wp_remote_get() genuinely cannot substitute; suppress with // phpcs:ignore WordPress.WP.AlternativeFunctions.curl_curl_init, WordPress.WP.AlternativeFunctions.curl_curl_setopt_array, WordPress.WP.AlternativeFunctions.curl_curl_exec, WordPress.WP.AlternativeFunctions.curl_curl_getinfo, WordPress.WP.AlternativeFunctions.curl_curl_close -- wp_remote_get() does not support sub-second connect timeouts and a comment, but be aware human reviewers may still flag it.

• cURL in drop-ins / mu-plugins / bundled assets/*.php is also rejected — the "HTTP API isn't loaded that early" excuse does not hold — PCP and human reviewers scan every PHP file shipped in the package, including early-loading drop-ins (fatal-error-handler.php, object-cache.php, advanced-cache.php, db.php, sunrise.php). A drop-in that phones home (e.g. a fatal-error handler sending a crash alert) is the classic place developers reach for curl_init()/curl_exec() because wp_remote_post() may not yet be loaded that early — but the cURL is still flagged (WordPress.WP.AlternativeFunctions.curl_curl_init / _curl_setopt_array / _curl_exec / _curl_close) and rejected. The correct pattern is a function_exists() guard that skips the request when the API is unavailable — never a cURL fallback:

  // Best-effort notification. By the time a plugin/theme fatal fires, wp_remote_post()
  // is normally loaded; for a rare fatal before the HTTP API loads, it simply isn't sent.
  if ( function_exists( 'wp_remote_post' ) ) {
      wp_remote_post( $url, [ 'timeout' => 5, 'blocking' => false, 'body' => $body ] );
  }
  

  Skipping a best-effort alert in the rare pre-bootstrap-fatal case is acceptable; shipping cURL is not. Audit: grep -rn "curl_init\|curl_exec\|curl_setopt" assets/ includes/ *.php — drop-in and asset .php files are easy to miss because they are not loaded through the main plugin bootstrap.

• set_time_limit() flagged as discouraged — add // phpcs:ignore Squiz.PHP.DiscouragedFunctions.Discouraged -- required to prevent PHP timeout on large backups on each call.

• Direct DB queries ($wpdb->query() etc.) flagged as discouraged — the complete phpcs:ignore comment requires three sniff codes, not two: // phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery, WordPress.DB.DirectDatabaseQuery.NoCaching, PluginCheck.Security.DirectDB.UnescapedDBParameter -- [reason]. Omitting PluginCheck.Security.DirectDB.UnescapedDBParameter leaves a second wave of warnings: Plugin Check traces every variable used in a DB call back to its assignment and flags it as "assigned unsafely" if the assignment is not a recognised safe source. This fires on $table, $cnt, $ref_table, $date_expr — any variable in the query string. The proper resolution depends on the variable type:

  • Table names derived from $wpdb->prefix — use esc_sql() at assignment: $table = esc_sql( $wpdb->prefix . 'plugin_tablename' );. This satisfies the sniff without a suppression comment, signals intent to reviewers, and is safe because $wpdb->prefix contains only alphanumeric characters and underscores.
  • SQL expressions from an internal conditional (e.g. $cnt = $unique ? 'COUNT(DISTINCT visitor_hash)' : 'SUM(view_count)') — not user input, cannot be parameterised. Suppress: // phpcs:ignore PluginCheck.Security.DirectDB.UnescapedDBParameter -- internal SQL expression selected from a hardcoded conditional, not user input.
  • $limit_sql, $date_expr, $placeholders — same pattern: suppress if the value is built entirely from trusted/validated internal data; fix at the assignment with absint() / intval() / esc_sql() if any part could be external.

• PluginCheck.Security.DirectDB.UnescapedDBParameter fires even when $wpdb->prepare() is used — Plugin Check's own sniff runs separately from PHPCS's WordPress.DB.PreparedSQL.InterpolatedNotPrepared. A query can pass $wpdb->prepare() correctly (all user values parameterised) and still get flagged for UnescapedDBParameter on the interpolated table/column names. Both suppressions are needed for each query that uses both interpolated identifiers and prepared value placeholders.

• NonceVerification.Missing — PHPCS and the WordPress.org Plugin Check only recognise nonce verification when check_ajax_referer(), wp_verify_nonce(), or check_admin_referer() is called directly in the same function scope as the $_POST/$_GET/$_FILES access. A helper wrapper (e.g. ajax_check(), cs_verify_nonce()) that calls check_ajax_referer() internally is not traced — every $_POST read below it is still flagged. Fix: replace every helper call site with a direct check_ajax_referer() call. Adding phpcs:disable NonceVerification.Missing is not a substitute — Plugin Check still flags the violation.

Verification

After fixes are applied, confirm:

• Review report was produced and user confirmed before any file was touched
• PCP checklist passes with zero errors in all addressed categories
• All three version strings match
• CHANGELOG.md has a dated entry for this change
• No helper functions duplicated — Utils is the single source of truth
• Every new function has a DocBlock with @since, @param, and @return

References

Failure modes

• Hidden files in the distribution zip — WordPress.org automated scanning rejects any plugin containing files whose names begin with . (e.g. .distignore, .gitignore, .env, .DS_Store). The error is hidden_files: Hidden files are not permitted. Fix: ensure every dot-file is listed in the rsync/zip exclusion rules used to build the distribution package. Check with unzip -l plugin.zip | grep '/\.' before submitting.

• Echoed <script> or <style> tags — the single most common WordPress.org rejection. Grep the entire codebase for <script and <style before submitting. Every hit is a violation. Use wp_enqueue_script(), wp_add_inline_script(), wp_enqueue_style(), and wp_add_inline_style() exclusively. See references/performance.md.

• Ownership mismatch — if the submitting WordPress.org username is not in Contributors:, or the account email domain does not relate to the plugin's declared URLs, the submission is held. Resolve via DNS TXT record, email change, or account transfer. See references/pcp-checklist.md WordPress.org submission section.

• Global asset enqueue — PCP flags CSS/JS enqueued on every page. Always gate on $hook in admin, conditional tags on frontend.

• Missing nonce — every AJAX handler and form needs one. The most common PCP security rejection.

• Duplicate helpers — always check Utils before writing. Copy-paste across files causes divergence and is a review failure.

• Version mismatch — if the three version strings differ, WordPress.org validation will fail.

• Bare die() — use wp_die() in HTTP contexts. Bare die() is flagged by PCP.

• Missing ABSPATH guard — every included PHP file needs if ( ! defined( 'ABSPATH' ) ) { exit; } as its first executable line.

• Downgrading Tested up to — WordPress.org automated scanning rejects plugins where Tested up to is lower than the current WordPress stable release (error: outdated_tested_upto_header). Never lower this value during a review. If the value appears to be a future version, verify against wordpress.org/news before acting — the version may simply be ahead of the reviewer's knowledge cutoff. Only ever raise Tested up to, never lower it.

• Broken buttons after onclick refactor — when removing inline onclick attributes from PHP-rendered HTML buttons to satisfy PCP, the replacement JS event-binding code must use a stable selector. A common mistake is leaving the binding code as querySelector('[onclick="fnName()"]') — this selector worked while the attribute was present but returns null once the onclick is removed, silently dropping the click handler. The symptom is a button that renders correctly but does nothing when clicked, with no JS error. Audit rule: after every PCP onclick removal, verify that (a) the button has an id, and (b) addEventListener is attached via that id. Never use querySelector('[onclick=...]') as a binding selector — it is inherently self-defeating. See references/pcp-checklist.md §onclick refactor checklist.

• NonceVerification.Missing via helper delegation — PHPCS and the WordPress.org Plugin Check only recognise nonce verification when check_ajax_referer(), wp_verify_nonce(), or check_admin_referer() is called directly in the same handler scope. A shared helper (e.g. ajax_check(), cs_verify_nonce()) that wraps check_ajax_referer() internally is invisible to the sniff — every $_POST/$_GET/$_FILES access below the helper call is flagged, and phpcs:disable NonceVerification.Missing does not satisfy Plugin Check. Fix: replace every helper call site with a direct check_ajax_referer( 'action', 'field' ) call. The helper function can remain for other uses; just remove the delegation at each handler. Audit by grepping for helper calls in wp_ajax_ actions and confirming check_ajax_referer() appears directly in the same closure/function body. See references/security.md §Delegated nonce verification for the full pattern.

• Unhandled async function rejections (silent JS failures) — async functions called from onclick attributes return a Promise. If that Promise rejects (due to any runtime error — including calling .style on a null getElementById result, a network failure, or non-JSON response), the rejection is silently swallowed by the browser. The function stops mid-execution with no error message, no user feedback, and no console output unless console.error() is explicitly called in a catch block. The symptom is a button that appears to work but produces no result. Audit rule: every async function must wrap its entire body in try { ... } catch(err) { console.error(...); /* show user message */ }. Loops that call async functions should re-enable disabled buttons in finally {}. All getElementById() results must be null-checked before property access. See references/coding-standards.md §JavaScript async error handling.

• PCP errors missed during manual review — the review skill catches patterns by reading code, but PCP runs PHPCS rules mechanically and flags things that look fine to a human reader (e.g. a variable holding 'checked' that is never user-controlled, but still needs esc_attr(); or date() used on a timestamp the developer controls). The only way to guarantee zero PCP errors is to run the WordPress Plugin Check plugin locally before submission. The review skill is a guide, not a substitute for a live PCP run. Always treat PCP output as the ground truth. Critical PCP-only catches:

  • date() → gmdate() (any date() call, regardless of context)
  • mt_rand() → wp_rand() — PCP flags WordPress.WP.AlternativeFunctions.rand_mt_rand as an error
  • parse_url() → wp_parse_url() — PCP flags WordPress.WP.AlternativeFunctions.parse_url_parse_url as an error on every native call; always use wp_parse_url() instead
  • unlink() → wp_delete_file()
  • rmdir() / readfile() → WP Filesystem
  • wp_die('string') → wp_die( esc_html__( 'string', 'slug' ) )
  • exec() / shell_exec() / system() / passthru() → must be removed entirely — adding phpcs:ignore is not a fix; WordPress.org reviewers reject the plugin outright regardless of whether escapeshellarg() is used
  • file_put_contents() / file_get_contents() without phpcs:ignore — WordPress.WP.AlternativeFunctions.file_system_operations_*
  • fopen() on remote URLs — use wp_remote_get() / wp_remote_post(); many hosts block PHP stream wrappers for remote access
  • fread() / fclose() / fwrite() → WP Filesystem API ($wp_filesystem->get_contents() / $wp_filesystem->put_contents()). PCP flags WordPress.WP.AlternativeFunctions.file_system_operations_fread, _fclose, and _fwrite the same way it flags fopen; all four functions are violations
  • slow_db_query_meta_key — PCP warns whenever meta_key appears in a WP_Query/get_posts() call (WordPress.DB.SlowDBQuery.slow_db_query_meta_key). The fix is to ensure the column is indexed, or suppress with // phpcs:ignore WordPress.DB.SlowDBQuery.slow_db_query_meta_key -- indexed on post_id and meta_key
  • PreparedSQLPlaceholders.ReplacementsWrongNumber — $wpdb->prepare() received a different number of replacement values than there are %d/%s/%f placeholders in the query string. This is a real bug, not a style warning — fix the placeholder count, do not suppress
  • wp_verify_nonce() called with only wp_unslash() on the nonce value — must use sanitize_text_field( wp_unslash( ... ) ) because wp_verify_nonce() is pluggable
  • WP_CONTENT_DIR . '/subfolder/' for writable storage — use wp_upload_dir()['basedir'] . '/plugin-slug/' for all persistent file storage outside the database
  • Logging a raw superglobal value before the sanitize_*() call on the same or a later line — WordPress.org flags this even with a phpcs:ignore InputNotSanitized comment; sanitize first, log after
  • Any unescaped intermediate variable in HTML output
  • Missing wp_unslash() on superglobals — even for integer casts, use (int) wp_unslash( $_POST['field'] ?? 0 )
  • $_SERVER superglobals (HTTP_HOST, REQUEST_URI, SCRIPT_NAME, etc.) require the same treatment as $_POST: validate the key exists (?? ''), wp_unslash(), then sanitize_text_field(). PCP fires InputNotValidated, MissingUnslash, and InputNotSanitized on every bare $_SERVER[...] access. Preferred pattern: avoid $_SERVER entirely for URL construction — use home_url(), admin_url(), wp_parse_url( home_url(), PHP_URL_HOST ), and add_query_arg() instead. These WordPress helpers are already slashed/sanitised and produce the correct value regardless of server config. Direct $_SERVER reads for URL building are almost always replaceable by a WordPress equivalent.
  • Text domain not matching WordPress.org slug (derived from plugin name, not folder)
  • readme.txt: >5 tags, >150-char short description
  • printf()/sprintf() with a placeholder in an i18n string — must have /* translators: %s: description */ on the line immediately above; PCP flags WordPress.WP.I18n.MissingTranslatorsComment as an error on every missing comment
  • __( 'Text', $td ) / esc_html__( 'Text', $text_domain ) → __( 'Text', 'plugin-slug' ) — text domain must be a string literal in every i18n call (WordPress.WP.I18n.NonSingularStringLiteralDomain); one Critical error per call — a class with a shared $this->td property and 25 translated strings generates 25 errors
  • _e( 'Text', 'slug' ) / _ex( 'Text', 'ctx', 'slug' ) → esc_html_e( 'Text', 'slug' ) — _e() and _ex() output unescaped; replace with the escaping variants
  • esc_url_raw( $url ) in output context → esc_url( $url ) — esc_url_raw() is a sanitiser, not an output escaper
  • json_encode( $data ) → wp_json_encode( $data ) —

…(truncated)