You have gone through your regular module update routine and cleared the cache. Suddenly you are presented with a PHP Fatal error, because a class can’t be found. Your Drupal site won’t load and you can’t run Drush commands. All you get is the fatal error blocking the site.

An example

On a recent project, a newer version of the Entity Cache module was added and tested.

This is normally pretty trivial, but after clearing cache using Drush, I was presented with the following error:

PHP Fatal error:  require_once(): Failed opening required '/var/www/examplesite/sites/all/modules/entitycache/entitycache.taxonomy.inc' (include_path='.:/usr/share/pear:/usr/share/php') in /var/www/examplesite/includes/bootstrap.inc on line 3161 

The Drush command terminated abnormally due to an unrecoverable error.                                                                 

Why can’t Drupal find the class?

The cause was pretty simple - the Entity Cache module had been restructured and files that contain classes had changed location.

Why does moving files cause an error? Why can’t Drupal just load from the new location?

This is because paths to various classes are stored in the registry table in the database. This reduces the number of files Drupal needs to load to process a request and reduces memory usage.

If you get a fatal error like above where a class is not found, a likely cause is that the Drupal registry has the old path for the class. A cache clear should update, but sometimes it all goes a bit wrong.

The solution is to rebuild the registry. This will update the registry table with the new file locations. The [Registry Rebuild] project gives you the tools to do this.

Install and running Registry Rebuild using Drush

Normally you could install registry rebuild and run it using Drush.

Download and enable Registry Rebuild:

drush en registry_rebuild -y

Rebuild the registry:

drush rr

rr is an alias for the registry rebuild command.

But if the site is blocked because of the fatal error, you will not be able to install the module or run the Drush command. This is because Drupal is loading the class with the old path in its bootstrap, which it needs to run even when you are installing and running registry rebuild. So the very thing that you need to run to fix the problem, you can’t actually run until you fix the problem!

Installing and running Registry Rebuild without Drush or Drupal

Fortunately, there is another handy way to run registry rebuild. This way doesn’t require a full Drupal bootstrap, so will run without the pesky fatal error.

Steps:

• Download registry rebuild from Registry Rebuild into your modules folder and untar it
• On the command line, cd to the registry_rebuild folder. In that folder, you will see a file called registry_rebuild.php
• We want to run that directly using PHP, so run the following command:

php registry_rebuild.php

Once it has finished, the registry table will be rebuilt and will contain the new path for your class. You can now go about your Drupal business without the fatal error. Happy days.