wp-cli-pattern-validate

A WP-CLI command that round-trips WordPress block pattern files through core's own parse_blocks() / serialize_blocks() to produce the exact markup WordPress would write after a Gutenberg save. Useful for enforcing consistent pattern formatting in CI or as a pre-commit check.

$ wp imagewize pattern-validate web/app/themes/your-theme/patterns/
PASS  hero.php
FAIL  cta.php
   1 of 2 files need changes. Re-run with --fix to apply, or --diff to preview.

Why this exists

Block pattern .php files are hand-edited, but WordPress re-serializes block markup on every save through its own parser — normalizing attribute order, whitespace, and escaping along the way. A pattern file that looks fine can still drift from what WordPress would actually store, which shows up later as an unexpected diff the first time someone edits it in the editor. This command runs that same round-trip ahead of time, so the drift is caught in review instead.

Installation

wp package install imagewize/wp-cli-pattern-validate

Or pin a version:

wp package install imagewize/wp-cli-pattern-validate:^1.0

No further setup — Composer's autoloader picks up command.php and the imagewize pattern-validate command is available on every wp invocation after that.

Requirements

• WP-CLI 2.x
• PHP 7.4+
• diff binary on $PATH (standard on macOS and Linux)
• WordPress must be bootstrapped for parse_blocks() / serialize_blocks() to be available — run wp from a WordPress install as usual (--path or a wp-cli.yml pointing at one)

How it works

1. Reads each .php pattern file and extracts the block HTML (supports both the return 'string'; format and the PHP docblock + raw HTML format).
2. Passes the block HTML through parse_blocks() then serialize_blocks().
3. Reverses the unicode escapes WordPress adds to <, >, &, and -- so that PHP open/close tags, CSS custom properties (--wp--…), and literal & survive round-tripping unchanged.
4. Compares original vs. canonical — reports PASS / FAIL, optionally diffs or fixes.

Usage

# Validate all patterns — dry run, shows PASS/FAIL per file
wp imagewize pattern-validate web/app/themes/your-theme/patterns/

# Show a unified diff for each file that needs changes (no writes)
wp imagewize pattern-validate web/app/themes/your-theme/patterns/ --diff

# Auto-fix all structural issues in-place
wp imagewize pattern-validate web/app/themes/your-theme/patterns/ --fix

# Fix and save per-file diff logs + a summary to docs/pattern-logs/<date>/
wp imagewize pattern-validate web/app/themes/your-theme/patterns/ --fix --log

# Override the log output directory
wp imagewize pattern-validate web/app/themes/your-theme/patterns/ --fix --log --log-dir=/tmp/pattern-logs

# Validate a single file
wp imagewize pattern-validate web/app/themes/your-theme/patterns/hero.php --fix

# Validate a subdirectory only
wp imagewize pattern-validate web/app/themes/your-theme/patterns/woocommerce/ --fix

Options

Flag	Description
--fix	Rewrite each non-canonical file in-place
--diff	Print a unified diff to stdout (dry-run, no writes)
--log	Write per-file .diff logs and a summary.md to docs/pattern-logs/<date>/
--log-dir=<path>	Override the default log directory
--compliance	Run project-specific compliance checks after structural validation
--compliance-only	Skip the Gutenberg round-trip; run only compliance checks

Exit codes

Code	Meaning
0	All files pass (or all issues fixed)
1	One or more files need changes (dry-run) or a write error occurred

WooCommerce patterns

Files under a woocommerce/patterns/ path are automatically skipped — they follow WooCommerce's own standards rather than your theme's.

Compliance hook

The --compliance and --compliance-only flags call run_compliance_checks(), which is a stub in this package. Adapt it to point at your project's own static-analysis script:

// Inside run_compliance_checks():
$checker = '/path/to/your/project/scripts/pattern-check/class-compliancechecker.php';

Projects that don't need this can leave the stub as-is — the flags emit a warning and exit cleanly.

Log output structure

With --log, each run creates:

docs/pattern-logs/
└── 2026-05-30/
    ├── hero.php.diff
    ├── card.php.diff
    └── summary.md

summary.md contains a per-file status table (PASS / FIXED / NEEDS_FIX) and counts.

Source

This command started as a WP-CLI script inside imagewize/wp-ops, which also exposes it as wp-ops wp-cli-pattern-validate / trellis ops wp-cli-pattern-validate for ad-hoc use outside a package install. This repository is the packaged, standalone distribution of the same command.

License

MIT