WordPress Coding Standards 3.4 can change or add findings across an established plugin. Suppressing every new error restores a green build quickly, but it can also hide real security, compatibility, documentation, or style regressions in files that continue to change.
Use this for WordPress plugins, themes, mu-plugins, agency repositories, and maintained legacy projects that enforce PHPCS in pull requests.
Quick answer
Run the old and new dependency locks on the same commit, diff findings by sniff and file, fix high-value violations first, and scope any baseline to exact legacy lines or paths. Add a changed-files gate and ratchet the baseline count downward over time.
What to check first
- Pin PHP, PHPCS, WPCS, PHPCompatibility, and installer versions for the old and new comparison runs.
- Export machine-readable reports and group findings by sniff, severity, file, line, and whether the line changed recently.
- Review security, escaping, sanitization, nonce, capability, database, PHP compatibility, and documentation findings before cosmetic style.
- Use exact exclude-patterns or scoped annotations only where immediate correction has unacceptable risk.
- Fail CI when the baseline grows, a suppressed line changes, or a new file introduces a baseline entry.
Diagnostic table
Use this table to keep the work practical. It connects the symptom to evidence and a verification step.
| Action | Evidence to collect | How to verify |
|---|
| Lock the old and new toolchains | Pin PHP, PHPCS, WPCS, PHPCompatibility, and installer versions for the old and new comparison runs. | The same commit produces reproducible reports on local and CI runners. |
| Diff findings by exact sniff | Export machine-readable reports and group findings by sniff, severity, file, line, and whether the line changed recently. | Every new sniff category has an explicit fix or scoped disposition. |
| Fix high-risk findings first | Review security, escaping, sanitization, nonce, capability, database, PHP compatibility, and documentation findings before cosmetic style. | Changed files cannot rely on a stale blanket exclusion. |
| Scope necessary legacy exclusions | Use exact exclude-patterns or scoped annotations only where immediate correction has unacceptable risk. | The baseline count is measured and can only stay flat or fall. |
Why this usually happens
- A ruleset release can add sniffs or correct detection behavior.
- Dependency ranges can install different PHPCS components on separate runners.
- Broad file exclusions are easier than classifying legacy debt.
- Line-based suppressions can drift when nearby code changes.
Useful command or data shape
Adapt paths, IDs, and privacy handling to the site before running commands or storing data on production.
# Compare on the same commit
composer update wp-coding-standards/wpcs --with-dependencies
vendor/bin/phpcs -q --report=json > wpcs-3.4.json
# CI policy
baseline_new_entries: 0
changed_files_must_pass: true
baseline_total_must_not_increase: true
Safe fix order
Do the work in a sequence that makes each result easy to prove. Stop if a step produces new evidence that changes the incident scope.
- Lock the old and new toolchains
- Diff findings by exact sniff
- Fix high-risk findings first
- Scope necessary legacy exclusions
- Ratchet the baseline in CI
Decision rule
Pass when new and changed code has no unreviewed violations, legacy exclusions are narrow and owned, dependency versions are deterministic, and the baseline cannot grow silently.
What to tell the client or owner
Give the owner the affected versions, exact workflow, observed result, business impact, evidence location, temporary control, named owner, and next review time. Remove credentials and personal data from shared screenshots and logs.
Production verification checklist
- The same commit produces reproducible reports on local and CI runners.
- Every new sniff category has an explicit fix or scoped disposition.
- Changed files cannot rely on a stale blanket exclusion.
- The baseline count is measured and can only stay flat or fall.
Mistakes to avoid
- Do not change several plugins, cache rules, or infrastructure settings before preserving a baseline.
- Do not treat one successful test as proof for retries, alternate clients, background work, or mixed-version fleets.
- Do not paste secrets, personal data, complete production payloads, or customer files into tickets or screenshots.
- Do not close the test until the final user-visible state and the server-side evidence agree.
Questions teams ask during testing
Should we fix every historical style finding before upgrading?
No. Classify by risk, fix what can change behavior or security first, and isolate remaining debt without allowing new occurrences.
Is excluding the vendor directory enough?
Vendor should be excluded, but application-level generated code, third-party bundles, and legacy paths still need intentional ownership and scope.
When HandL WP should help
Bring in HandL WP when a production checkout, form, email, media pipeline, code-quality gate, or paid lead workflow is at risk. We can preserve evidence, isolate the failing layer, make the smallest corrective change, and verify the result across WordPress, connected services, logs, and the user journey.
If this is active on a production site, upgrade WordPress plugin quality gates.
Related HandL WP guides
Use these related guides when the same issue touches tracking, security, checkout, or crawler visibility.
Evaluate AI patches in an isolated WordPress fixture
For model-generated code changes, run the Ox Alpha WordPress sandbox test with public fixtures, pinned versions, read-only tools, PHPCS, PHPUnit, security checks, role tests, human review, rollback, and scored recovery effort.
Helpful references