Migrate margin and padding helpers

Use this command when upgrading a POM site whose legacy pages or templates still use pixel-named spacing classes. It requires WordPress with POM Theme, WP-CLI, a staging copy, and a full database/settings backup. Run it before reopening the upgraded site to editors and visitors: the retired pixel helpers have no frontend compatibility aliases.

To migrate fonts, gaps and spacing together in one scan, use the unified helper migration. All four commands share the same application, backup and cache behavior.

Replacement map

The same suffix map applies to m, mt, mr, mb, ml, p, pt, pr, pb, and pl:

The new 8 suffix provides 8rem; it has no automatic legacy replacement. These are approximate design equivalents, not an exact pixel conversion. mauto, unsupported mr-auto, and zero helpers are left unchanged.

Run the migration

1. Back up the database and managed templates. Pause editing and scheduled imports during application. Upgrade POM Theme and the matching first-party plugin templates together on staging.

2. Inspect the current site without writing:

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

3. Review the summary and manual-review notices; add --verbose to list every proposed location. Add --network to inspect all POM-theme sites in the current network; other themes are skipped. Shared user metadata, network options and shared templates require the separate --include-shared opt-in because they may serve other themes.

4. Review the informational notices in the CLI output. Unresolved values are skipped in full and left unchanged; they do not prevent safe locations from being migrated. You can review and correct them manually after application. A class list mixing old values with compact names such as pt-1 needs a decision: previously undefined compact classes would acquire a rem meaning. Correct them in the source, pass reviewed exact removals such as --remove-compact-classes=pt-1,pb-1, or use --keep-mixed-classes only after confirming that their new rem meaning is intended.

5. Provide an existing private directory outside WordPress with mode 0700, and apply the same reviewed scope:

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

   Each run creates a private backup plan before its first content write. It contains exact original and proposed values; keep it private with the full pre-upgrade backup. Do not publish it as a downloadable report.

6. Verify the stored results with another dry run:

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

   The migration leaves all caches and generated assets unchanged. Existing cached responses can continue showing old content until the normal cache lifecycle or separately managed refresh takes effect.

7. Check representative legacy pages, archive/feed/single templates, translated pages and responsive layouts before reopening the site. Confirm the second dry run reports no safe replacements and review any remaining manual-review notices.

Scope and preservation

The command inspects all post types and statuses, revisions, excerpts, standard metadata, options, term descriptions, comments, and managed POM Framework settings/templates. It changes recognized HTML class attributes, legacy shortcode class attributes, supported structured class fields, and CSS selectors. It understands scalar/array PHP serialization, JSON, base64 HTML, base64 URL-encoded HTML such as vc_raw_html, entity-encoded markup, and historic slashed template markup. Managed PHP templates are parsed as text, never executed.

It does not change arbitrary numeric attributes, inline margin/padding declarations, responsive Page Builder spacing, font sizes, gaps, shortcode names, post dates, or Gutenberg block spacing attributes. It does not scan or rewrite theme/plugin source files; upgrade their supplied templates with their corresponding product versions. Third-party custom tables, external templates and opaque binary formats require a separate inventory. Serialized objects/references and unresolved code fragments are reported for manual review, not rewritten.

No cache cleanup occurs, including on a repeat --apply with no replacements. Object caches, individual cache entries, OPcache, translation skeletons, editable-style transients, generated assets and page/CDN caches are preserved. Cache and asset maintenance are separate site-owner operations.

Options and failure handling

• --dry-run: explicit simulation; this is also the default without --apply.
• --apply: writes safe locations after preflight; values requiring manual review remain unchanged.
• --backup-dir: required for application; existing, private, writable and outside WordPress.
• --network: all POM-theme sites in the current network.
• --include-shared: explicitly include shared data.
• --batch-size: indexed read batch size, 25–2000; default 250, reduced for large values.
• --verbose: list every proposed location alongside phase progress.
• --include-network-options: add current-network options without other shared data.
• --keep-mixed-classes: explicit acceptance of compact classes mixed with old pixel classes.
• --remove-compact-classes: comma-separated exact compact classes to remove from recognized class lists that also contain a retired pixel helper. This legacy-value boundary prevents a repeated run from deleting legitimate new rem classes.
• --fail-on-remaining: also return a failing exit status when a dry run finds safe replacements.

Manual-review notices appear directly in the terminal, not in WordPress log files. Each notice identifies the site, exact file or database location, option/metadata name when available, detected field, helper names when available, and the reason it was skipped. The review hint distinguishes JavaScript, custom CSS/SCSS, templates, or other stored content/settings using the available field name or file extension. Encoded values may report the decoded field and helper names. The entire skipped value is preserved, including any otherwise convertible classes inside it.

The summary counts skipped values under manual_review, separately from blocking issues. Manual-review notices alone return a successful exit status, including with --fail-on-remaining; that flag checks safe replacements only. Read/write failures, oversized rows or managed files and invalid rewritten PHP still block or stop application. Progress and interruption recovery follow the unified guide. Changes are idempotent. Application checks that each original value has not changed since preflight and stops rather than overwriting concurrent edits. Application is not one transaction across the database and filesystem: a failure after writes can leave a partially migrated site. Keep it closed, review the reported count and backup plan, and either resolve the cause and rerun or restore the coordinated database/settings backup. Do not restore only one side of an HTML/PHP template pair.

Values larger than 16 MiB, encoding/structure nesting beyond 16 levels and unsupported formats require manual handling. Backups are retained until you explicitly remove them after verification.

Related guides

• Spacing helper reference
• Gap helper migration
• Font-size helper migration