Migration Blues After Step 3
So you decided to migrate your site to a new host and you’ve got your Full backup zip file and importbuddy.php in place in your new site root: Step 1, select the file; Step 2, select Migrate; Step 3, files extracted – looking good; Step 4 – what is this? Why is my browser showing me all this stuff that I don’t understand or asking whether I want to download and save a file, this isn’t what I was expecting – HELP!
Well your old host just had the last laugh – when this happens it’s almost always because of a file that was unzipped into your site root from the backup file and almost always it’s the .htaccess file that’s causing the issue.
Give Me The Gory Details
The .htaccess file can be used by WordPress to instruct the server how to handle permalink vs real file/directory accesses but crucially it may also be the way that your host instructs the server how it should handle PHP script files which are the bedrock of applications like WordPress.
This may be done by including special directives that instruct the server in how to handle files with a specific extension, for example, importbuddy.php having the .php extension should be handled as a PHP script file and processed accordingly. If the server is improperly instructed then it may handle the file incorrectly.
For example, in order to get PHP files to be processed as PHP5 scripts a host might require the following directive in your .htaccess file in your site root:
AddHandler x-httpd-php5 .php
which instructs the server to process any file with the .php extension using the associated handler.
But what if that directive is invalid on your new host, that referenced handler doesn’t exist? The server could just give up and throw an error, or in the interests of doing something it may fall back to use some default handler which generally just treats the file as a text file, either to be displayed or downloaded.
So the problem described above comes about because over on your old host there was either a specific directive in the .htaccess file that was valid on that server or perhaps there was no directive at all, the server gets it’s instruction in some other way. When the .htaccess file is backed up and then migrated to the new site it may overwrite any existing .htaccess file or become the de facto file if none existed originally. Then either the presence of an invalid handling directive or perhaps the absence of a valid handling directive causes the server to do something like serve up importbuddy.php as a text file, or try to have it downloaded through the browser.
So how do we go about fixing this?
Well of course prevention is the best cure, so can we prevent it? Well we can’t really stop the .htaccess file from being migrated but we can be forearmed and ready to fix it after Step 3 in the Migration process and before proceeding to Step 4.
[Note: strictly speaking we could prevent the .htaccess file from being written to the new site by either setting the permissions of the existing .htaccess file to read-only or if no .htaccess file exists creating an empty one with read-only permissions - that way the unzipped .htaccess file should not overwrite it. However, for the purposes of this article let's take the broader view.]
First thing is to look at your BackupBuddy Server Info page and have a look at the Server Configuration information, and specifically the “Add Handler in .htaccess” parameter. The AddHandler directive is one of the ways (as shown above) in which PHP handling may be enabled on a server so if your .htaccess file contains one or more of these statements you will get a warning because potentially, if you migrate to a new server, you may get a problem as described earlier. This is one example of how BackupBuddy is being enhanced to help you in your day-to-day activities, additional such tests will be added over time to help warn you abut potential problems with migrations.
However, you should still take a direct look at your .htaccess file because there are other possible directives that may cause problems so the idea here is to be aware of these, not necessarily to know how they work but to be able to compare them with what you may or may not see over on your migrated to site. Generally speaking these “troublesome” directives come at the start of the file so that’s where to pay most attention.
So now we have an idea what’s happening on the source site, what about over on the site we are migrating to? Now you may or may not have a .htaccess file in your site root by default – this can depend on whether the server needs any specific directives to process PHP script files correctly or not in the case where this is configured by other configuration files that you have no, and need no, access to.
If there is no .htaccess file present it could also just mean that currently the new host account isn’t configured for PHP yet, you should check with your host support or on your control panel to see whether PHP is enabled. If not, the make sure it is enabled before continuing.
If you do find a .htaccess file then immediately take a copy of it, download it to your desktop or copy it to some other directory in your hosting account. Then open it up with an editor and take a look, is it empty, are there any directives similar to those on your source site that seem to be related to .php files but may be are slightly different from those on the source site? Keep this in mind as you start the Migration process.
Getting it Done
So, winding on a bit, you’ve now just completed Step 3 of the Migration and all the files are unzipped – time to pause the Migration, don’t hit that Next Step button but instead switch to your ftp client or control panel File Manager (or however else you look at and edit files on your new site) and take a look into the .htaccess file that is now sitting in your site root.
Suppose neither this file nor the original file that you took a copy of earlier have any directives that look as though they have anything to do with determining how .php files are processed by the server, all you see is a bunch of stuff surrounded by “BEGIN WordPress” and “END WordPress” – in that case you should be good to go, click that Next Step button in your browser and continue the migration – well done, things are looking good.
On the other hand, what if you see an AddHandler directive that you were warned about, or something similar, but you don’t see anything like that in the .htaccess file that you saved a copy of earlier from your site root. In that case you’ll want to consider using your editor to either delete those lines or simply comment them out by inserting a hash “#” character at the start of the suspect line – this will prevent it from being processed – remember to save the file after making the update. Now you can proceed with the Next Step button in your browser to continue the migration.
A third possibility is that the .htaccess file you are looking at either contains no such directives or it does contain such directives but they are not the same as those in the file you saved a copy of earlier. In that case consider copying the directives from the saved file (the file originally in your site root) into the current .htaccess file as these are likely required for your new server to be able to correctly process .php files like importbuddy.php – remember to save the file after making the edit. Now you can proceed with the Next Step button in your browser to continue the migration.
By working through the above instructions you should be able to avoid one of the commonest issues with Migration, often known as the “Problem after Step 3 of the Migration” problem.