Download the PHP package imagewize/pt-cli without Composer

WordPress Pattern Toolkit

Scaffolding, compliance checking, and HTML template validation for WordPress FSE block themes.

Generates block pattern PHP files, layout patterns, and style variations. Checks pattern .php files for structural and naming rule violations, and checks HTML template/part files for client-side block validation drift — no WordPress context required. Runs on the host machine as a standalone PHP CLI tool.

Installation

As a global tool:

Or as a project dev dependency (recommended for theme development):

Then use ./vendor/bin/pt-cli or add a Composer script.

Requires PHP 8.1+.

Usage

Scaffolding Commands

Compliance Checking

HTML Template Compliance

Pattern Diff & Sync

Compare a Gutenberg clipboard paste against an existing PHP pattern file, or apply the changes back while preserving all PHP translation wrappers.

What --apply does:

1. Strips editor-only attributes (__privatePreviewState) from block JSON.
2. Fixes bare font-size slug values (font-size:small) → CSS variable (font-size:var(--wp--preset--font-size--small)).
3. Removes nested <p> copy artefacts introduced by the Gutenberg clipboard.
4. Re-maps every text node back to its original PHP wrapper (esc_html_e, esc_attr_e, wp_kses_post) from the existing file.
5. Generates a new esc_html_e() wrapper for any text that is new in the clipboard.
6. Preserves the PHP docblock header unchanged.

The file is only written when --apply is used without --dry-run.

Commands Reference

Workflow

pt-cli is an all-in-one tool for WordPress FSE block theme development:

Scaffolding Workflow

Pattern Sync Workflow (updating existing patterns)

When an existing PHP pattern needs updating from the Site Editor, use pattern:diff --apply instead of pasting manually — it keeps all esc_html_e() and other PHP wrappers intact.

Compliance Workflow (three-pass)

Pass 1 requires WordPress (database connection) and runs in the Trellis VM. Passes 2 and 3 are standalone and run on the host machine.

Templates

23 pre-built pattern templates covering common use cases:

WooCommerce templates:

Layouts

8 layout skeletons for rapid page construction:

Style Variations

5 preset color palettes for common business verticals:

Snippets

13 reusable code snippets for common pattern components:

Configuration

Built-in configs ship with the tool:

• base — default rules for any FSE theme
• elayne — Elayne-specific rules (extends base)

Project-level override

Create .pt-cli/{theme}.json in your project root to override or extend the built-in config without needing a pt-cli release:

Config lookup order:

1. .pt-cli/{theme}.json (project directory)
2. config/{theme}.json (tool directory)
3. config/base.json (fallback)

Rules

Base rules (all FSE themes)

Elayne-specific rules (--theme=elayne)

Autofixable rules (--autofix)

Exceptions

• Templates (template-*, header-*, footer-*) allow: border-radius:5px, border-radius:100px, blockGap:0.5rem, blockGap:10px
• WooCommerce plugin patterns (wp-content/plugins/woocommerce/patterns/*) are exempt from all checks

Template rules (check:templates)

Applied to .html files in templates/ and parts/ directories. These checks catch client-side JavaScript save() mismatches that the PHP compliance checker and WP-CLI structural validator cannot detect.

Why separate from check?

The check command processes PHP pattern files. HTML template files use a different structure — raw block markup without PHP wrappers — and require different checks. In particular, WooCommerce 9.x+ changed the save() output for filter blocks to include empty <div> wrappers; templates written against older versions lack those wrappers and trigger client-side block validation errors that neither WP-CLI nor the PHP checker can catch.

Demo Rebuild Script

For rebuilding demo pages from pattern PHP files, see the Demo Rebuild Script guide.

Development

License

MIT — see LICENSE.