Migrate font-size, gap and spacing helpers together

Use wp pom migrate-helpers to upgrade legacy font-size, spacer, margin and padding helpers in one pass. This guide is for site owners and developers who run WP-CLI. It requires the updated POM Theme, access to the target site's command line, and a private backup directory for application.

The individual migrate-font-size-helpers, migrate-gap-helpers and migrate-spacing-helpers commands use the same engine and options, limited to their named family. All four commands default to a dry run. Font-size and gap commands also require --apply and --backup-dir to write.

Preview and apply

1. Keep a coordinated backup of the database and managed settings. Verify the upgrade on staging and pause editing and imports during application. Do not run an older migration concurrently with the new command.

2. Preview the selected site:

   wp pom migrate-helpers --url=https://example.test --dry-run

3. Review the summary and any manual-review notices. Add --verbose to print each proposed location. The default reports progress even when no replacements are found.

4. Provide an existing writable directory outside WordPress, accessible only to the account running WP-CLI (mode 0700). Apply the reviewed scope:

   wp pom migrate-helpers --url=https://example.test --apply --backup-dir=/private/migrations

5. Keep the private helpers-<run-id>/plan.jsonl backup until verification is complete. The command saves exact original and proposed values before its first content write. A backup failure prevents application.

6. Verify that no safe replacements remain:

   wp pom migrate-helpers --url=https://example.test --dry-run --fail-on-remaining

7. Inspect representative pages, feed/archive/single templates, fixed typography, Gap blocks and responsive spacing in the editor and frontend. Review any skipped values separately.

Progress and performance

Each site, content store, managed-file scan, backup and application phase is identified. A progress bar updates approximately every two seconds while work advances. Database percentages describe progress through a fixed ID range, not a percentage of rows: deleted IDs can make the percentage jump. The separate inspected count reports actual rows. Managed files use an indeterminate bar and a file count, avoiding a second directory scan. Backup and application bars have known totals. Output is also readable when redirected to a log.

The command fetches complete values in batches rather than querying each metadata row individually. --batch-size accepts 25–2000 rows (default 250); large values reduce the effective batch size. Rows added beyond a store's initial upper ID are left for a subsequent run. Oversized rows/files are reported before application. Progress cannot advance while a database or filesystem operation is blocked; the named phase identifies the work in progress. --debug=pom-migrate-helpers prints operations before they start when more detailed diagnosis is needed.

Scope and preservation

By default, --url selects one POM-theme site. All post types and statuses, revisions, excerpts, standard metadata, non-transient options, term descriptions, comments, and managed POM Framework settings/templates are inspected once for the selected families. The command does not rewrite theme/plugin source, uploads, third-party custom tables or external templates. Backups, temporary migration files, cache directories and minified managed assets are excluded.

• --network processes the current network's POM-theme sites; other themes are skipped.
• --include-shared explicitly adds shared user metadata, current-network options and shared managed templates. These can affect other sites and themes.
• --include-network-options adds current-network options without adding user metadata or shared files. Selected sites' own site metadata is already included.
• Shared data is not included automatically by --network or --url.

Serialized scalar/array values, JSON, supported base64 and URL-encoded payloads, and managed PHP strings are processed without evaluating PHP or instantiating serialized objects. Unsupported objects/references, ambiguous spacing, and unresolved code are left unchanged and reported. A skipped value is preserved in full, including otherwise convertible helpers inside it. Arbitrary numeric values, post dates, shortcode names, inline margin/padding declarations and Gutenberg spacing attributes are preserved. Legacy Gap blocks are the explicit block-attribute conversion.

The exact replacement maps are documented in font sizes, gaps, and margin/padding.

Cache behavior

All four commands leave caches and generated assets unchanged. They do not flush object caches, delete individual cache entries, invalidate OPcache, remove translation skeletons or editable-style transients, purge page/CDN caches, or regenerate assets. Writes retain stored content dates and bypass content-save hooks.

Existing cached responses or PHP bytecode can therefore continue showing previous content until the site's normal cache lifecycle or a separately managed refresh takes effect. A successful migration confirms stored values, not that every cached frontend response already reflects them. Cache and asset maintenance remain separate site-owner operations.

Repeat runs and interruptions

Completed replacements are preserved. You can run the unified command after a partially completed older font-size, gap or spacing migration; it reads the current stored values and changes only remaining legacy helpers. It neither restores old backups nor repeats conversions of current rem tokens. An interrupted dry run has made no content changes.

Application is not a transaction covering the whole site. On a write failure, earlier successful locations remain migrated and their exact originals remain in that run's backup. Resolve the reported cause and run the same command again; there is no checkpoint or restart ID to supply. Retain backups from every run if a full rollback may be needed. The command checks original values before writing and stops on detected concurrent changes. Concurrent new-engine applications are rejected immediately.

A stopped progress bar is followed by a Migration failed record in normal output as well as the error on standard error. The record includes the exception, current location and number of applied locations without printing the stored content. A failure during preflight has applied zero locations. Preserve the complete output when diagnosing a failed run; a launcher's exit-code label alone does not identify the cause.

A spacing class list mixing old pixel classes with compact names such as mt-1 is reported for review. Use --keep-mixed-classes only if the compact names already have their intended rem meaning. Alternatively, --remove-compact-classes=mt-1,pt-1 removes reviewed exact compact names only from recognized lists that still contain a legacy spacing helper. Fully migrated lists remain unchanged on reruns.

Read/write errors, oversized rows/files and invalid rewritten PHP stop or block application. Unsupported values appear under manual_review and remain unchanged while safe locations can proceed. --fail-on-remaining makes a dry run fail when safe replacements remain; manual-review notices remain informational and must be reviewed independently. Values above 16 MiB and nesting beyond 16 levels require separate handling.