Troubleshooting 101
This first bit is about as simple as it gets: typos. Typos are the leading cause of frustration and broken keyboards (well, I think so.) Drupal utilizes naming structures for its hooks and files. Having a typo in a hook or file name can cause some of the biggest issues but also be overlooked. If your hook isn't working make sure you spelt your module or theme name right. Second, double check your hooks naming. There have been numerous times when my hook didn't fire because I misread the API. For example, maybe you're implementing hook_ctools_plugin_post_alter() and deleted "ctools", leaving mymodule_plugin_post_alter(). Also make sure if your hook is supposed to handle variables by reference (using an ampersand [&]) or return a value. Alter, preprocess, and process functions all pass variables by reference. API implementation hooks usually require a returned value, like hook_block_info(). If dealing with Views or Rules you need to make sure your automatically loaded files are named properly. Views integration checks for mymodules.views.inc and mymodules.views_default.inc. On the other hand, which I always mess up, Rules checks for mymodule.rules.inc and mymodules.rules_defaults.inc. Note the different? Views is "default" and Rules is "defaults".User Permissions
Have you ever set up a portion of your Drupal site to find it functioning when logged in as an admin, but when logged out it is broken? That's because authenticated users, anonymous users, and "root" user are handled different.- "root" user is the first administrative account created when the site was installed. The user with uid 1 bypasses all permission access checks (and is the only one who can import Views through the UI!) Basically when you're logged in as the initial admin you won't be able notice permission problems.
- authenticated users are anyone logged into the system, regardless their role. What makes this important is that authenticated users bypass some of the caching Drupal provides. Authenticated users will bypass page cache and even some block caching (as specified by the block.) anonymous users will get every bit of cached data Drupal has at its disposal thrown at them. That means an anonymous user could be viewing stale page data stored in cache that a logged in user may see just fine.
Cache, Cache, Baby
Drupal has a pretty epic structure. Hooks are invoked in modules, themes, even profiles. That means Drupal has to scan module files to find hook implementations, and you could imagine how costly that'd be to run on each bootstrap. Drupal provides a set of its own cache tables, including a general cache, and modules can define their own as well. That's why this post gets its title. If you added a hook, made a big change, sometimes even after enabling a module, you may want to clear the cache. How do you clear the cache? In order to flush the cache through Drupal's UI you need to visit admin/config/performance and click "Flush all caches." This will clear out all of the caches in the system and help resolves 80% of your problems. Enable a module and the configuration pages comes up as a 404? Flush the cache. Updated your regions and blocks and the change isn't displaying for anonymous users? Flush the cache. The problem with the "Flush all caches" button is exactly what it says - it will blow away every cache, causing them to be rebuilt. Using Drush or Admin Menu you can choose specific caches to clear. This can also be completed through the MySQL command line, or phpMyAdmin if you prefer, after all its just database entries. For the scope of the article we'll assume the use of Admin Menu since its simply a module and not a command line tool like Drush.Stop, clear cache and listen
Let's break down some of the different cache table. This isn't meant to dive into the mechanics, but to explain why its beneficial to clear specific caches versus everything at once.- Generic cache is a collection of random cached items. This includes module schemas, ctools cache, node types, etc. Generally if a module has to scan modules for information it will store the data in cache so it won't have to re-scan modules on each load. You can only clear this cache by clearing everything, or manually truncating the database table.
- Page cache stores the actual output of pages for anonymous users. That way Drupal has less to bootstrap and returns a rendered page much faster. Drush and Admin Menu provide a way to clear page cache. For example, you moved a block into a different region and notice the change when logged in, but not logged out.
- Block cache stores the output of block content based on a multitude of ways as defined by the module that provides the block. You can only clear this cache by clearing everything, or manually truncating the database table.
- Aggregated CSS-JS files aren't cached in the database, however they are still a cached state of all the stylesheets Drupal uses. Clearing the CSS-JS cache will cause Drupal to rebuild the aggregates. If CSS/JS aggregation is enabled this allows theme style changes to render. Drush and Admin Menu provide shortcuts to flushing these files.
- Menu cache is all of the known paths within Drupal and their callback functions. Ever have a module's configuration page come up as not found? Try clearing this cache and see if it works again. Drush and Admin Menu provide a method for clearing the menu cache.
- Theme registry isn't so much a cache but a list of theme functions and templates that Drupal is aware of. That means the theme registry has to be flushed in order for Drupal to be aware of new theme template files or theme function overrides (modules as well.) Drush and Admin Menu provide quick links to flush this cache.
Want more? Sign up for my weekly newsletter