How to Override Features

The Features module helps address the shortcoming in Drupal 7 of how to manage and deploy site configuration data.  There are times when you need to change a Feature.  The Features Override module can help with this, but sometimes doesn't solve the problem completely.  In this article I will discuss all the different ways to override your Features and the common problems associated with that.  While this has been an issue for years, it's become more common recently with the advent of Distributions such as Open Atrium and Panopoly which heavily use Features and which expect the users to upgrade to new versions.  Maintaining your site customizations when upgrading a distribution using Features Override has become a more common need.

The Problem

How do I override configuration from an existing Feature  within my site-specific project?

Solutions

Cloning the base module (not recommended)

If you need to make extensive changes you might need to clone the base module and then customize it.  Disable the original module, uninstall it, then enable your site-specific module.

Using settings.php

If you just need to change a variable (from variable_get) you can do this via the $conf[] array in your site settings.php file.  This method is typically used for environment-specific settings, such as databases, search servers, caching settings, etc.  You can also set the $conf[] array within a custom module if you need to deploy the change across all your environment.  Avoid using variable_set() to change the variable since that will update the database directly as mentioned below.

Update the Database directly

You can create an update hook, or other Drupal hook (hook_enable, hook_install) and update the database directly via SQL or other API functions.  For variables you can use variable_set() to save the new value to the database.  This is only recommended as the last resort for configuration not supported by Features Override. If you must update the database directly, be sure to only do it once and not in a hook such as hook_init that runs with each page load.  Updating the database on each page load can kill the performance of your site.  With variable_set() you can do this by first calling variable_get() and only saving the value if it needs to be changed.

Implement an "alter hook" in code

Most configuration has some sort of "alter" hook that allows it to be modified after it is loaded from the database.  For example, Views calls hook_views_default_views_alter(&$data) to allow you to change any part of a view, whether that view comes from the DB or is in code.  You can create a custom module that implements the desired alter hooks and override the data directly.

Use Features Overrides module

Similar to the above "Implement alter hook" the Features Override module is designed to create the alter hook implementations for you and export those as new Features modules that you can enable, disable, deploy.

Typical Problems

Feature is stuck at being "overridden"

The most common difficulty is a base Feature marked as "overridden" that does not go away when the feature is reverted.  "Overridden" simply means that the value of the configuration stored in the DB is different from what is stored in the exported Feature code file.  Features literally re-generates the feature export internally from the DB and compares the code with what is stored on disk.  Doing a "drush fd featurename" simply shows the code diff between the code stored on disk (shown in red) with the code generated from the current database (shown in green). To determine if a Feature is overridden, Features actually takes the generated code, sanitizes it, sorts it, executes it, and then does an md5 checksum on it.  If the two checksum values are different, the Feature is marked as "overridden".  However, the "drush fd featurename" command shows the actual code difference regardless of if it's marked as "overridden". This behavior means that "drush fd" might output code differences that actually don't cause the feature to be overridden.  For example, if you change the order of dependencies in your module.info file and then run "drush fd" on the feature, you'll see it display those changes, even though a "drush fl" won't show the feature as overridden. This makes it difficult sometimes to debug why a feature is overridden, since not all of the output of "drush fd" is relevant.  You need to look for actual value changes, rather than just re-ordering changes.

Adding a new module

Sometimes, just enabling a new contrib module will cause your Features (especially field features) to be "overridden".  If the new module adds some new settings, formatters, widgets, etc then these settings will be active in the DB but not reflected in the code.  So the Feature will be shown overridden.  Reverting the feature won't have any affect because there is no way to remove the new settings from the DB without uninstalling the new module. These kinds of overrides are annoying, but not actually that important.  They don't prevent the feature from being reverted when a new version of the base module is released.  They are not caused by any site-specific change that would be lost by a revert.  Typically it's best to just document these cases and leave them as overridden.  Just be careful to not become complacent and make a site customization in the future to the same feature and then ignore that it's overridden and lose your changes when you revert.  You should periodically do a "drush fd" on overridden features just to be sure what is shown is still just from the new module you installed.

A disabled module

Similar to the above, but the opposite case.  If you have disabled a module that was used when the original Feature was exported, then the code might have settings for that module that are no longer in your database.  Once again you won't be able to remove this by reverting.  Again, you can just document these cases.  But make sure you really need to have the module disabled.  Having a module enabled that you are not using is not a big performance impact.  The time saved in long-term maintenance of the site it typically more important than worrying about an extra module.

A bad override

If you have used some of the not-recommended approaches for overriding a base Feature, such as writing directly to the DB, then you will end up with an overridden feature that cannot be reverted.  Or if the Feature is reverted, you might lose the change that was written to the DB and need to reapply it.  Even if the Feature is locked to prevent reverting, it will still be listed as overridden. Another type of "bad override" is using the wrong kind of alter-hook to try to modify configuration.  If the alter hook is called in a way that makes it look like a DB change to Features, then Features is going to see a difference between the DB and code and mark it as overridden.

Overridden Views and Panels

Some modules, such as Views and Panels have their own "override" functionality.  These "pure" Features can exist purely in code with nothing in the DB.  When you make a UI change to a View, it gets copied from the code into the DB and your change is made to the DB.  The View is then marked as "overrides code" in the Views listing.  A View that came from code can be "reverted" within the Views UI.  This essentially just deletes the version of the view in the DB so that the code takes affect again. Sometimes you can get a View stored in the DB that still matches the code.  For example, you change a View in the UI (causing it to be copied to the DB), then you edit the View and undo the change.  Now it matches the code again, but the view is still in the DB.  In this case, the View Feature will not be shown as "overridden", but in the Views listing it will still say "overrides code". When changing a pure Feature like a View via code (like in an alter hook), your changes will take affect immediately, or possible after a cache clear.  No revert will be necessary because there is nothing in the DB to update.  However, in the above case where you have changed a view and then changed it back so it's stored in the DB, changing the code will not affect the View until you revert the Feature to remove the DB copy of the old view. In general, if you are having issues with Views, Panels, or other ctools-like pure Features, make sure they are not overridden in their respective UIs.  For example, click the Revert option for the View within the Views listing to ensure it's actually using the View stored in code.

Wrong version of Features

If the code in the Feature was exported using a different version of Features than what is on your site, there might be changes that cause overrides.  Ensure your version of Features matches the version used to generate the export.  This usually only applies to major version numbers and is not normally a problem.  Normally updates to the Features module are made in backwards-compatible ways to prevent this.  But certainly be sure your version of Features on your site is not older than the version that generated the base code.  Always try the latest version of Features to see if it helps. Nobody should be using the 1.x branch of Features anymore.  There is no reason for this.  All Drupal 7 sites should be on the 2.x branch.

Unsupported Component

As mentioned, not all configuration components support Features Override, or only support it partially.  For example, Panelizer works with Features, but doesn't work well with Features Override because it still depends on the specific order of items in it's config array and when the alter-hook generated by Features Override tries to change something, that array order might not be preserved.  Sometimes in this case you can create your own alter-hook implementation that overrides the code properly. This might also be an opportunity to help improve Features Override or suggest patches to the module in charge of the configuration to better support Features Override.

Living with Overrides

What if you have tried all of this advice and your Feature is still marked as overridden?  And what if this override represents a specific site change that you need to maintain and ensure never gets reverted?  The solution to this is to "lock" your feature component.  Go to the Structure/Features page and select the Feature that is marked as overridden.  Click the small "lock" icon next to the overridden component in the right column.  The component will still be listed as "overridden" but when you revert your Features the locked component will be skipped, ensuring that your customization remains in place. When locking your Features, try to only lock the specific component rather than locking the entire Feature.  The downside to locking a component is that any changes to that component from a new version of your distribution won't take affect.  This is similar to the consequences of the "Update the Database directly" option listed above.  However, sometimes this is the only alternative.

Conclusion

Just keep in mind that both Features and Features Override are just implementing hooks (normal hooks for Features, alter-hooks for Features Override) that are exposed by Drupal or contrib module.  If those hooks don't exist or don't work properly there isn't much Features or Features Override can do about it.  Drupal 7 doesn't have any sort of configuration management in core, so every contrib module does it differently.  ctools-based modules have more of a standard framework, as does entity API.  Features itself tries to add code to handle core components such as Fields, Content Types, etc that don't have the needed hooks.  But there is often a limit to how much Features can do and just patching stuff into the DB is not usually a good solution. Don't "hate" Features or Features Override.  Life was much worse without them.  They are the best solution to solving configuration management problems in Drupal 7.  They have been developed over years of experience.  Try to help improve them before trying to implement your own configuration or override architecture.

Drupal 8

Don't count on Drupal 8 magically solving all of these issues.  The Configuration Management Initiative (CMI) within Drupal 8 was focused on handling site configuration, but not on "bundling functionality".  It provides an API, storage mechanism, and framework for deploying configuration.  CMI helps a lot, but there are still issues around around component granularity and overriding configuration.  In Drupal 8, configuration is owned by the site rather than owned by a module.   This will make bundling functionality (ala Features original intent) more difficult.  We will be working on Features for D8 soon, but this is still mostly unknown territory.  For now, take a look at some existing modules such as config_packager and config_devel. I've submitted a session to DrupalCon Los Angeles on Features in Drupal 8.  Add a comment and support!