[Theme: Delicate] Theme Options lost when moving to new domain

What I do when I change domains is to go into the database and change the all the URLs.

I have seen a lot of people fall in this trap. I am not familiar with this theme at all, but my guess is that it uses the WP Settings API to store options in an array in the DB. Ordinarily the options would get stored thus:
name => value

So, you would get something like:
'background_image' => 'https://path.to/old/url'

But using the WP API if you save the options, the options get encoded. So you get something like this:
type:length:value

Note that apart from the value, you have the length that is stored. So, your background_image option above also gets the number 22 assigned for the length (the path is 22 characters long).

When you are doing a find/replace via the DB, you are basically changing the URL to ‘https://new-path.to/old/new-url’, which is 30 characters long, but your option still says “22”. This corrupts your options array.

This is true of any theme that uses the WP API to save options. You could write a PHP script to fix problem. The script will:
1. Retrieve option names for options that have the old domain URL in them.
2. Use the WP call get_option to fetch the complete options. This takes care of decoding.
3. Do a find/replace of the old URL with the new URL for all the matching options.
4. Use update_option to save the new values. This will take care of the lengths etc.

I am not sure if a plugin of this sort exists, and if it doesn’t, there is certainly a market for one.

Thank you very much for your excellent explanation, Sayontan. I’ve been hit by this one a few times. I should know better by now. I guess some theme developers are unaware of this. Thanks, helped a lot.

There is absolutely nothing wrong with what the theme developers are doing.

@esmi,

There is absolutely nothing wrong with what the theme developers are doing.

I agree. This is an area that the theme users need to be cognizant about and understand why the “search and replace in the DB” approach to migration doesn’t work.

That’s going to be so hard to explain to non-technical users, though. Perhaps it’s worth bringing up on the theme-review list as a topic for discussion since so many themes are now using the Settings API (my own included)? Perhaps a recommendation could be added to the effect that any theme that saves urls in a serialized array should consider displaying a warning?

Just a thought…

This is an area that the theme users need to be cognizant about and understand why the “search and replace in the DB” approach to migration doesn’t work.

So what’s the best way to migrate a WP site? It doesn’t seem like WP documentation covers everything – are we supposed to manually change the URL one by one? There has got to be a better way…

Moving_WordPress is still the best resource in terms of documentation but serialized arrays are a special problem all on their own. I don’t think there is an accepted best practice way of handling them yet.

are we supposed to manually change the URL one by one?

You can’t. That’s the point. In the database, they will be stored in a “coded” format that simply won’t be recognised by a simple search & replace.These stored strings would have to be unserialized, checked, updated if necessary and then re-serilaized again – which wouldn’t be a trivial task.

Got it. Thx! I guess the easiest solution for now is to do what I’ve been doing – write down all the theme options and change them once the site is migrated. I hope WP will update their documentation with a warning.

This is a core issue, not a Theme issue. Themes that are using the Settings API, and that implement core handling of features such as custom backgrounds, custom image headers, and custom nav menus are already doing things correctly.

Also, the data are not “encoded”; rather, the arrays are serialized. That has two implications:

1) The data are easily accessible, via the theme_mods_{themeslug} entry in the wp_options database table
2) The data can be changed directly, but since the array is serialized, that means that the array knows the string length of the value; so if you change the value such that the string length changes, you have to update the string length value in the array as well.

For example, I just did a test install of Twenty Eleven, and defined a header image. Here are the current contents of the theme_mods_twentyeleven entry in wp_options:

a:3:{s:18:"nav_menu_locations";a:1:{s:7:"primary";i:0;}s:16:"header_textcolor";s:3:"000";s:12:"header_image";s:89:"https://wptrt.chipbennett.net/wp-content/themes/twentyeleven/images/headers/chessboard.jpg";}

Note this, particularly:

s:89:"https://wptrt.chipbennett.net/wp-content/themes/twentyeleven/images/headers/chessboard.jpg";

Hey, look! That’s my custom header image URL! The s:89 is the string length I mentioned earlier.

If I were to change my root domain from wptrt.chipbennett.net to wptrt2.chipbennett.net, I would then need to change s:89 to s:90. And that’s it! I’m done.

So, no: it’s not an automated process; but by the same token: it’s not a difficult process, once you know what to look for.

This is a core issue, not a Theme issue.

I agree completely but could (should?) theme developers consider incorporating a warning for non-technical users? There’s nothing in Moving_WordPress that deal with urls in serialized arrays and (I’d imagine) the Search & Replace plugins might not be able to deal with arrays either. Although I do not consider that it is a theme developer’s responsibility to try and educate users, they may be best placed to do so in this situation.

If that’s not an option, then perhaps we should look at amending the Codex to deal with it?

…but could (should?) theme developers consider incorporating a warning for non-technical users?

Again, IMHO, no. It’s a core issue, and if a warning is necessary, such warning should come from core. The issue exists regardless of what Theme is used, so having every Theme developer come up with an implementation and wording for such a warning would present a horrible UX for end users, since such implementation/wording would be nigh-impossible to have any consistency from Theme to Theme.

+1 to updating the Codex, though. In fact, Ipstenu has already written a great post on the topic of dealing with data serialization when moving WordPress, that would make for a great starting point.

Ok – I’m off to twist some arms to see if we can get a better Codex page.

Arm twisted! I’m working on it ??

ETA – If you chose to ‘search and replace’ the DB, I would suggest ONLY doing that on wp_posts. You can actually leave the rest alone in most cases, and your themes won’t break. Shouldn’t…

What about theme options stored in wp_options?

Fantastic tip on serialization Chip. It solved my issue when moving a site to a domain with a longer url. The custom background and photo from the first site seemed to be lost. Found and changed the theme_mods options name in the wp_options table in the database and it worked like a charm. As you said, it’s easy when you know where to look.