Configuration

Configuration in Drupal is the information about how your site is set up, as opposed to what it publishes. It covers the site name, enabled modules, content types, fields, taxonomy vocabularies and views. Drupal keeps it in the database by default, and you can export it as YAML files and import it on another copy of the site.

How configuration works in Drupal 11

Drupal separates configuration from other kinds of information. Content is what visitors see and editors change. Configuration is the more permanent setup of the site. State is data that changes often or automatically, such as when cron last ran. Session data belongs to one visitor's interactions.

The live copy is called the active configuration, and by default it sits in the config table of the database. Two kinds exist. Simple configuration is a named set of values, such as system.performance, where the name starts with the module that supplies it. Configuration entities, such as a content type, store each item as its own row in that table.

Developers read simple configuration with \Drupal::config('system.performance'), which returns a read-only object. To change a value they call getEditable(), then set() and save(). Setting a value without saving it does nothing.

Exported configuration lives in the sync directory. By default Drupal places it inside the site's files directory, and you can move it after installation. For an import to work, the exported files must carry the same site UUID as the target site, so you copy configuration between copies of one site, not between unrelated installs.

Example

You add a field to a content type on your local copy. On your live site you want the same field. Use Drush and follow the practice described under configuration management:

drush config:export   # local: write the sync directory
        # copy the sync directory to the live site
        drush config:import   # live: review the list, answer y

Use drush config:status to see the differences between the database and the files, and drush config:get system.site to print one configuration object.

Common mistakes

• Editing configuration on the live site. The Drupal documentation recommends against making configuration changes on a live site. Make the change on a development copy and export it.
• Exporting over unsaved work. The Drupal.org guide to the Drush workflow warns that config:export deletes the current contents of the sync directory. Check what is in it first.
• Editing a module's config/install files. Drupal reads that directory only when the module is installed, so changing the files later does not change the active configuration.
• Forgetting overrides. A $config value in settings.php takes precedence over the stored value, but the admin screens do not show it. A setting that "will not change" is often overridden there.
• Importing from the wrong site. A mismatched site UUID stops the import. Move configuration only between copies of the same site.

For marketing and content teams

Whenever you change a setting rather than a page, you change configuration: a new content type, a vocabulary, a view that lists your articles. Those changes do not travel with your content. Ask your developers how they move configuration to the live site, and avoid making the same change by hand on two environments, because the two copies then drift apart. Day-to-day publishing does not touch configuration at all.

Sources

• Drupal.org: Configuration management
• Drupal.org: Managing your site's configuration
• Drupal.org: Overview of configuration versus other types of information
• Drupal.org: Simple Configuration API
• Drupal.org: Configuration override system
• Drupal.org: Configuration workflow using Drush
• Drupal.org: Introduction to the Entity API in Drupal
• Drush config:export command
• Drush config:import command