Block Migrator and Repair in GT ACF Blocks

Lesson 17 of 17
  • KPrevious lesson
  • FSearch lessons
  • EscClear search

Why This Exists

Old content accumulates problems: blocks saved under names the plugin no longer registers, accordion data stored with retired sub-field names, and markup the block parser chokes on. The Block Migrator & Repair system, added in 2.8.0 and improved in 2.8.1, finds all of it and fixes it in place, reversibly.

You’ll find it as the Block Migrator & Repair card at Settings > ACF Blocks License. Scan first, migrate second, and revert if anything looks wrong. Every change goes through wp_update_post(), so a native revision is stored on top of the plugin’s own restore points.

What the Migrator Fixes

Legacy and Renamed Blocks

Blocks saved under retired names are remapped to the current block with field-data translation, not just a rename:

  • acf/table-of-contents and acf/table-of-content to acf/toc
  • acf/productbox to acf/product-box, including the legacy features repeater
  • acf/accordion-item to acf/accordion (consecutive items merged into one block)
  • acf/accordion-group to acf/accordion (wrapper and children merged, FAQ schema preserved)
  • acf/acf-accordion to acf/accordion (acc_question/acc_answer sub-fields remapped)
  • acf/poll has no current equivalent. It’s reported and left untouched for manual handling.

Legacy Accordion Field Schema

acf/accordion blocks whose data still uses the old acf_accord_heading/acf_accord_content sub-fields render blank on the current template. The migrator remaps them in place to acf_accord_group_title/acf_accord_group_content, preserving FAQ schema and classes. If you’ve seen blank FAQ sections on older posts, this is the cause and the fix.

Unparseable Markup

Three parser-breaking patterns are repaired: orphaned closing delimiters (a stray <!-- /wp:post-content --> with no opener silently pushes every following block into freeform text), dangling openers (a truncated <!-- wp: fragment with no closer), and a literal --> inside ACF block JSON, which gets HTML-encoded so it renders identically without ending the comment early. The delimiter cleanup uses a stack, so only genuinely unmatched closers are stripped.

Running a Migration

Flowchart of a GT ACF Blocks migration: scan, dry run, then 30-post batches where each post is snapshotted as a native revision plus a restore point before wp_update_post writes changes, with Revert Migration and Discard restore points as the two exits
  1. Scan for issues. Lists every affected post with title, status, edit/view links, and color-coded badges showing exactly what will change.
  2. Dry run. Same analysis, nothing written.
  3. Migrate. Posts are processed 30 per batch with a progress bar and a Continue button for the next 30, so big sites never hit PHP time limits. Each batch shows the same per-post detail for what it just changed.

Reverting

Before each post is migrated, its original content is snapshotted twice: as a native WordPress revision (visible in the editor’s Revisions browser) and as a per-post restore point that works regardless of your site’s revision settings. The Revert Migration button rolls the entire multi-batch session back byte-for-byte. Discard restore points clears the backups without changing migrated content once you’re satisfied.

Block Recovery (the “Attempt Recovery” Fix)

Related but separate: includes/block-recovery.php handles InnerBlocks blocks whose inner content was saved as undelimited raw HTML (a bare <p> instead of a <!-- wp:paragraph --> pair). The editor flags these as invalid, and clicking Attempt Recovery rebuilds the block from its template default, wiping your content.

The recovery helper re-wraps orphaned inner HTML into proper core blocks (paragraph, heading, list, quote; anything unrecognized is preserved verbatim in a core/html block, so nothing is ever lost). It runs two ways: a live self-heal that filters the editor’s REST content.raw so affected posts open cleanly with no action required, and a permanent bulk repair via WP-CLI. The set of InnerBlocks block names is derived automatically and can be customized with the acf_blocks_recovery_innerblock_names filter.

WP-CLI

# Migrator: scan, migrate in batches, revert, clean up
wp acf-blocks migrate --dry-run
wp acf-blocks migrate --limit=30
wp acf-blocks migrate --revert
wp acf-blocks migrate --discard

# Recovery: permanent bulk repair of raw inner HTML
wp acf-blocks repair-content --dry-run
wp acf-blocks repair-content --post=123

CLI and the visual card share the same engine, so a scan in one matches a scan in the other.

Quick answers to common questions:

Is it safe to run the migrator on a large production site?

Yes, that’s what the batching is for. Posts migrate 30 at a time, every change is revisioned plus snapshotted as a restore point, and Revert Migration rolls the whole session back byte-for-byte. Run Scan and a dry run first, then migrate.

My old FAQs show empty accordions. Will the migrator fix them?

Yes. Blank FAQ sections on older posts almost always mean the accordion data uses the retired heading/content sub-fields. The migrator remaps them to the current field names in place, keeping FAQ schema and classes intact.