Writing

How to Fix Changed File Paths in Drupal

Here is the most likely situation: You started creating your Drupal platform by just adding modules to "sites/all/modules" and later decided to create a profile for your setup. You have a couple of sites running on the old version and a couple sites running on the new version. You decide to move the old sites to your nifty new profile. This is where the trouble begins.

Now suffice it to say, there are steps you can take to mitigate this issue beforehand. This article assumes that you did not take those steps, that you have just set up the connection between the old database and the site at its new location, and you are now staring at a WSOD and scratching your head. This also assumes that you have access to your database either via shell or some other tool like PHPMyAdmin that allows you to run SQL commands. Here is what to do:

Backup the Database

Any time you are going to make changes to a database (or any sort of file) it is a good idea to back it up. In PHPMyAdmin, select the correct database in the list on the left side and then click on the Export tab. You can likely just go with the default settings. If you are doing this via shell, here is the command:

$ mysqldump -u root -p databasename > databasename.sql

You'll want to substitute and appropriate user for root if you don't have root access or prefer not to use it. Obviously you'll need to replace databasename with the actual name of the database.

Empty the Cache

Unfortunately, you are probably not going to have a way to clear the cache that is easy. If you use drush, you are probably used to being able to fire off drush cc all, 'nuff said. But the same issue that is causing your WSOD will also prevent drush cc all from working. It will complain about a fatal PHP error because a file or directory does not exist. What you are going to have to do instead is manually clear the cache tables by using some variant of the following command:

mysql> DELETE FROM cache;

Don't worry if that looks scary. As long as you are running. It is pretty straightforward. However, there are multiple cache tables, possibly as many as a dozen or more. You'll need to look at what cache tables there are and run that command for each one, swapping out cache with the appropriate table name. From the shell, you should be able to see all the tables in the database with:

mysql> SHOW TABLES;

After you have repeated this for each of the cache tables, go ahead and refresh your page in the browser... you may be in the clear at this point. If not:

Update registry and registry_file to Point to Current File Locations

For those of you who, like me, were previously unaware of the inner workings of Drupal's autoload functionality, this is another potential source of your problem. The registry and registry_file tables both store paths to the various files that may need to be loaded if a particular class is called.

Unfortunately, this is not quite as easy of a fix as clearing caches was. To be honest, I'm not sure if these tables are automatically re-built or not, so I decided to update all the incorrect references to "sites/all/modules" to point to "profiles/myprofile/modules". Here is the SQL command for this:

UPDATE registry SET filename = REPLACE(filename, 'sites/all/modules', 'profiles/myprofile/modules') WHERE filename LIKE "sites/all/modules/%";
UPDATE registry_file SET filename = REPLACE(filename, 'sites/all/modules', 'profiles/myprofile/modules') WHERE filename LIKE "sites/all/modules/%";

I don't think that the WHERE clause is actually necessary, but I believe that adding it will reduce the number of rows that need to attempt the replacement. You'll obviously want to replace "profiles/myprofile/modules" with the actual path to your profiles module directory relative to the root of the site.

Refresh the page... if you still get WSOD, you may want to try opening the site in another browser or clear the browser cache, to ensure you are not being duped by your browser's cache.

At this point you should be good insofar as you should be able to log in again and run drush commands. You may need to run updates too, if the version of any of your modules has changed.

I hope this guide helps you avoid the frustration of the day of work I lost to figuring this out.

Writing