Configuration Rewrite

Rewrite existing configuration during installation

Place any configuration .yml in your module's config/rewrite folder and declare config_rewrite a dependency to your module. Full and partial configuration changes are saved on installation.

Example Config Rewrite

file://mysite/docroot/modules/my_module/config/rewrite/lightning_core.settings.yml

content_roles:
  creator:
    enabled: false
  reviewer:
    enabled: false

The above configuration will partially override lightning_core.settings configuration. This will happen after my_module is installed but before hook_install is run.

Example Config Replace (Full replacement)

file://mysite/docroot/modules/my_module/config/rewrite/system.site.yml

config_rewrite: replace
name: 'My Site'
mail: admin@example.com
slogan: 'This site rules.'
page:
  0: ''
  1: ''
  front: /my-home
admin_compact_mode: false
weight_select_max: 100
langcode: en
default_langcode: en

The above configuration example will replace system.site entirely. The config_rewrite: value must be present at the top and set to replace -- this key/value pair will be stripped to retain config integrity before rewriting is completed.

Example Config Replace (specific keys only)

file://mysite/docroot/modules/my_module/config/rewrite/user.role.editor.yml

config_rewrite:
  replace: ["permissions"]
permissions:
  - 'change own username'

The above configuration example will replace only the designated keys. This is the most precise technique as it does not perform any array merging. If you are experiencing issues with the standard rewrite technique, consider adding an optional replace array to ensure the keys are rewritten correctly.

Some extra notes about overriding versus rewriting configuration files

This module came to be via working on Configuration Tools sub-module config_partial_override - which will actively override configuration at all times.

Configuration Rewrite (config_rewrite) only rewrites config during the extension's installation process.

If you want to actively override configuration, consider Configuration Override for full site overrides or Configuration Tools' Configuration Partial Override for module-based overrides.

Optional configuration is not supported by config_rewrite and attempting to rewrite config found in module's config/optional directory may lead to issues. We recommend using hook_install or traditional update hooks for those edge cases.

8.x-2.x dev version
The 8.x-2.x version that requires #2350111: Introduce an event to decouple the module installer from the entity manager is no longer under active development. We recommend using the stable 1.x releases going forward.