Drupal Study Guide

Appearance

Configuration Management ​

Goal: Demonstrate ability to use configuration management capabilities for exporting site configurations.

Overview ​

The configuration API provides a central place for modules to store configuration data. This data can be simple configuration like your site name, or more complex information managed with configuration entities, such as views and content types.

Configuration is a place to store information that you would want to synchronize from development to production. This information is often created during site-building and is not typically generated by regular users during normal site operation.

You should use the State API, not configuration, for storing local variables that shouldn't travel between instances. Use state for hidden system values, and if you never want to deploy it between environments. You can reset a system, losing all state. Its configuration remains.

The configuration API comes in two flavors - the (simple) Config API and the Configuration Entity API. The key difference is that the Config API is the singleton use case. A singleton is where there can be only a single instance of this configuration. A good example would be the site's name.

The Configuration Entity API should be used to store multiple sets of configuration - for example node types, views, vocabularies, and fields.

Updating the configuration API is vital to avoid fatal errors when updating themes and modules to work in Drupal.

Configuration management in Drupal 10 works similarly to how the Features module did in Drupal 7.

By default, configuration data is stored in the config database table. The configuration management system built into core allows you to import and export these configuration settings across multiple environments and formats.

Exporting Configurations ​

Exporting Full Site Configurations ​

  1. Make a configuration change to your system, such as the name of your site.
  2. Navigate to Configuration -> Development -> Configuration Synchronization -> Export
  3. Click ExportExport Full Site Configuration
  4. Your browser will download an exported file configuration tarball (e.g. config-ddev102-ddev-site-2024-10-17-20-04.tar.gz)

Exporting Single Items ​

  1. Make a configuration change to your system, such as the name of your site.
  2. Navigate to Configuration -> Development -> Configuration Synchronization -> Export -> Single item
  3. Select the type and name of the config item you wish to export. Export Item
  4. You can now copy and paste this configuration elsewhere for future reference.

Viewing Configuration Changes ​

  1. Make a configuration change to your system for something that was previously exported, such as the name of your site.

  2. Navigate to Configuration -> Development -> Configuration SynchronizationConfiguration Synchronization

  3. Click View DifferencesConfiguration Differences

  • The Active column indicates the current setting in your site.
  • The Staged column indicates the value from the previous export i.e. in the yml files.

Importing Configurations ​

Importing Full Site Configurations ​

  1. Obtain a previous export tarball (See Exporting Full Site Configuration above)
  2. Navigate to Configuration -> Development -> Configuration Synchronization -> Import
  3. Click ImportImport Full Site Configuration
  4. After reviewing your changes, click Import All.

Note

It is almost always better to use drush to check the configuration changes before importing them. Use drush cst or drush config:status to see what changes will be made.

Importing Single Items ​

  1. Obtain YAML from a previous export.
  2. Navigate to Configuration -> Development -> Configuration Synchronization -> Import -> Single item
  3. Select the type and name of the config item you wish to import and press ImportImport Item
  4. Click Confirm

Drush ​

View configuration settings using drush:

shell
drush config:get system.site
drush config:get system.site name
drush config:get system.site mail
# or
drush cget system.site
drush cget system.site name
drush cget system.site mail

Set configuration settings using drush:

shell
drush config:set system.site name 'My Company Website'
drush config:set system.site mail 'superman@kryptonite.com'
# or
drush cset system.site name 'My Company Website'
drush cset system.site mail 'superman@kryptonite.com'

To export configurations using drush:

shell
drush config:export
# or
drush cex

To import configurations using drush:

shell
drush config:import
# or
drush cim

Configuration Storage ​

You can alter the storage location of your configuration in your settings.php file (or comparable file in your system e.g. settings.local.php).:

php
/**
 * Location of the site configuration files.
 *
 * The $settings['config_sync_directory'] specifies the location of file system
 * directory used for syncing configuration data. On install, the directory is
 * created. This is used for configuration imports.
 *
 * The default location for this directory is inside a randomly-named
 * directory in the public files path. The setting below allows you to set
 * its location.
 */
# $settings['config_sync_directory'] = '/directory/outside/webroot';
$settings['config_sync_directory'] = '../config/sync';

Resources ​

Questions ​

What is the purpose of the Configuration API in Drupal?

The Configuration API provides a central place for modules to store configuration data, which can range from simple settings like the site name to more complex information managed with configuration entities, such as views and content types.

What are the two flavors of the Configuration API, and where is configuration data stored by default in Drupal?

The two flavors are the (simple) Config API and the Configuration Entity API. The Config API is for singleton use cases where only a single instance of the configuration exists, like the site's name. The Configuration Entity API is used to store multiple sets of configurations, such as node types, views, vocabularies, and fields. By default, configuration data is stored in the config database table.

How can we export the full site configuration, single configuration item and view configuration changes in Drupal?

To export full site configuration, navigate to Configuration -> Development -> Configuration Synchronization -> Export, and click Export. Your browser will download an exported file configuration tarball. To export single configuraiton items, navigate to Configuration -> Development -> Configuration Synchronization -> Export -> Single item, select the type and name of the config item you wish to export, then copy and paste the configuration elsewhere for future reference, after making a configuration change, navigate to Configuration -> Development -> Configuration Synchronization, and click View Differences. The Active column indicates the current setting in your site, while the Staged column shows the value from the previous export.

What does the Drush command do, and how can we set the configuration storage in Drupal?

Drush is a command-line interface tool designed to help developers and site administrators manage Drupal websites more efficiently. It provides a wide range of commands for performing administrative and development tasks without needing to navigate through the Drupal administrative interface. To set configuration storage, you can alter the storage location of your configuration in your 'settings.php' file (or comparable file in your system e.g. 'settings.local.php').