Exportable configuration

Last updated on
23 December 2016

If your module includes data structures that could be considered site configuration, you will probably want to make that data exportable so that it can be stored and transferred between multiple sites. Adding exportables support will make it possible for site administrators to export data and import it into a different site. It will also allow data from your module to be included in features, apps and distributions.

The good news is that solid APIs exist that make implementing exportables straightforward. It's a good idea to plan for exportables support early on in your module development process, as the main exportables APIs include extensive support for administrative UIs. By using one of these APIs, you can save a lot of coding that would be taken to produce custom admin forms and pages.

Concepts in exportables: machine names, overrides, reverting, cloning

Familiar examples of exportable configuration are image styles and views. In Drupal 7, you can create an image style through the UI and then export it to be used on another site or included in the code of a module. Similarly, the Views module includes support for views to live in code or in the database.

To be exportable, a data object must be identifiable by a machine name instead or in addition to a numerical ID.

Typically, an exportable configuration can have a number of different states. Naming conventions vary a bit, but the basics include:

  • Default: configuration that is stored in code.
  • Normal: configuration that has been made through the UI and is stored in the site database.
  • Overridden: configuration that exists in code (default) but has been edited via the UI and so also has a database version, which supersedes the original default version.

Exportables support typically includes the following actions:

  • Export: Create a code representation of the item.
  • Import: Add the item to the site based on a previous export.
  • Override: Customize a code-based item, creating a database version.
  • Revert: Delete database-level changes made to a code-based item.
  • Clone: Create a new item based on the existing item.

Exportables APIs

It's of course possible to implement custom exportables support in your module. But two proven and documented APIs exist in Drupal contrib that greatly facilitate the process.

Exportables and Features

The Features module automates the process of exporting configuration to code. Features include a set of hooks that can be implemented to provide custom Features support. However, if you make your configuration exportable via the Entity API or CTools, your entities will automatically be recognized by Features and feature authors will be able to select them and add them to features. See the Features documentation for more information.

The future of exportables

In Drupal 8, configuration will be stored in code by default thanks to the work of the configuration management initiative.