WP Serial Fix

Change WordPress URLs without breaking your site.

A raw SQL find-and-replace on a WordPress database looks like it worked, then widgets, theme settings, and page builder layouts quietly disappear. The culprit is PHP serialization: it records the length of every string, and your replacement changed the text but not the number. Paste the value here and replace it the safe way, or repair data a bad replace already corrupted.

🔒 Everything runs in your browser. Your data is never uploaded.

🧩 The bug that eats WordPress migrations

WordPress stores structured settings (widget layouts, theme options, page builder content) as PHP serialized strings. A serialized string looks like this:

s:19:"http://old.example";

The 19 is the exact byte length of the text between the quotes. Now imagine you move the site and run a database-wide find and replace, http://old.example becomes https://new.longer.example. The text changes, the number does not:

s:19:"https://new.longer.example";   ← length says 19, text is 26

PHP reads exactly 19 bytes, hits garbage where it expected a closing quote, and gives up. WordPress calls unserialize(), gets false back, and treats the option as empty. Your widgets vanish. The site does not error; it just quietly forgets things. This is the single most common way a WordPress migration goes wrong.

🔧 How the safe replace works

This tool does what WP-CLI does under the hood, except in your browser with no database connection. It parses the serialized value into its real structure, performs the replacement inside each string, and re-emits the data with every length prefix recomputed from the actual byte length. Multibyte characters are counted correctly (an accented letter is two bytes, an emoji is four), and it descends into serialized data nested inside other serialized data, which WordPress does constantly.

Paste a bare value or a whole column of them (one per line). Plain, non-serialized text is replaced normally and labeled as such, so you can run mixed content through in one pass.

🩹 Repair mode, for when it already broke

If you already ran a bad replace and the damage is done, repair mode is the undo you wish you had. It scans for string prefixes whose numbers no longer match their contents and rewrites each number to the correct byte length, carefully handling the tricky case where the text itself contains a quote followed by a semicolon. Paste the corrupted value, get valid serialized data back. It cannot invent data that was truncated and lost, but a length-prefix mismatch from a naive replace is fully recoverable.

🗺️ The safer migration, start to finish

  1. Back up the database first. Always. This tool helps with values, not with backups.
  2. Export the tables, or copy the specific wp_options / wp_postmeta values you need to change.
  3. Run the old to new replacement here in search and replace mode.
  4. Paste the corrected values back, or import the corrected export.
  5. If you are cleaning up after a replace that already ran, use repair mode on the affected values.

For a whole live database at once, the command-line wp search-replace is still the right tool. This page is for the common middle ground: a handful of values, a single stubborn option, a page builder layout, or a cleanup, without setting up WP-CLI or trusting a value to a website you do not control.

💬 Questions people ask

Is my data uploaded anywhere?

No. Parsing, replacing, and repairing all happen in your browser with JavaScript. There are no network requests after the page loads, which matters when the value you are pasting came out of a production database. You can read the small, dependency-free engine to confirm it.

Does it handle objects and nested arrays?

Yes. Arrays, objects (including the class name length), nested structures, and serialized-inside-serialized strings are all handled. Every string length is recomputed on output.

What about the whole database at once?

For a full database, use wp search-replace "old" "new" from WP-CLI, which streams every table safely. This tool is for values you have in hand, and for repairs.

Can I use the engine in my own project?

Yes. docs/serial.js is a dependency-free ES module: parse, serialize, isSerialized, strictReplace, and repair. MIT licensed.

🌱 Why I built this

Every developer who has moved a WordPress site has been burned by this at least once, usually at the worst possible moment, staring at a homepage that lost its widgets with no error to explain why. The fix is well understood but the tools all assume a server and a database connection. This is the version I wanted: paste the value, get it back correct, move on.