I had a client last month—a high-traffic magazine—moving from a development subdomain that used an emoji in the URL. Yeah, don’t ask why. They were finally moving to a clean ASCII domain, but their content was an absolute graveyard of Gutenberg blocks, JSON escapes, and Punycode. Total nightmare.
My first instinct, like any dev who’s done this a hundred times, was to reach for the blunt instrument: wp search-replace. I figured I’d just swap the domains in the database and call it a day. That was my first mistake. It turns out that when you’re dealing with the modern block editor, a simple string replacement is like performing surgery with a sledgehammer. You’re going to break things you didn’t even know were there. Just a straight-up mess.
Why WordPress Importer URL Migration Beats SQL Queries
The issue is that WordPress doesn’t just store plain URLs anymore. They’re wrapped in JSON strings inside block comments, encoded as HTML entities, or hidden inside CSS styles within a style attribute. A standard search-replace missed half of them and corrupted the other half. I ended up with background images that wouldn’t load and cover blocks that looked like they’d been through a shredder. Not good.
This is where the recent updates to the WordPress Importer come in. If you’ve been ignoring that plugin for the last few years (and let’s be honest, many of us have), it’s time to take another look. Specifically, the WordPress Importer URL migration features in version 0.9.5 are a game changer. And I don’t use that term lightly.
The importer now understands the context of the data it’s moving. It doesn’t just see a string of text; it uses the new structured data parsers in WordPress Core to identify what is actually a URL and what is just a coincidental string. It can handle Punycode, Unicode escapes in JSON, and even those weird %-encodings mixed with HTML entities that usually drive devs crazy.
<?php
/**
* Example of how the internal logic handles complex block markup
* during the migration process.
*/
class bbioon_Url_Migration_Handler {
public function bbioon_process_block_data( $content ) {
// The new importer uses BlockMarkupUrlProcessor under the hood.
// It catches things that a simple REPLACE() query misses:
// 1. JSON-escaped URLs: https:\/\/yummy-\uD83C\uDF7E-recipes.org
// 2. HTML Entity encoded URLs: https//...
// 3. CSS-encoded URLs in style attributes.
return $content;
}
}Under the Hood: The Orchestra of Parsers
Under the hood, this effort is powered by the BlockMarkupUrlProcessor. Think of it as an orchestra director coordinating several specialized parsers like WP_HTML_Processor and CSSProcessor. It knows that a CSS class name that looks like a domain shouldn’t be touched, but the background image URL inside that same block’s style attribute definitely needs to change. This level of nuance is exactly what we’ve been missing. Trust me on this, it saves hours of manual cleanup.
This isn’t just about saving a few minutes of work, though. On a massive site with hundreds of thousands of rows, running multiple UPDATE queries on post_content can lock up your most important tables for hours. Since this migration happens during the import process itself, those old URLs never even touch your new database. I saw a great breakdown of this over at make.wordpress.org recently, detailing how the WordPress/php-toolkit is finally making “data liberation” a reality.
So, What’s the Point?
The takeaway here is simple: stop treating WordPress content like flat text files. The block editor has made the database structure more complex, and our migration tools are finally catching up. Here are a few things to keep in mind for your next move:
- Always check the “Migrate URLs” box in the WordPress Importer 0.9.5+.
- Don’t rely solely on SQL search-replace for block-based sites.
- Test your Punycode and emoji-based domains thoroughly before going live.
Look, migrations are always going to be a bit stressful. But using tools that actually understand the data structure of the modern web makes the difference between a smooth launch and a weekend spent debugging someone else’s mess. If you’re tired of fighting with broken links and just want your site to work, drop my team a line. We’ve probably seen your exact problem before.
Leave a Reply