Browse files

Add storage filter hook for benefit of config_split and similar contr…

…ib/custom projects.

This brings back commit 7322efc.
  • Loading branch information...
1 parent 0f18539 commit 11ed42f77b6c728c2610b733c9075e2c06806c69 @bircher bircher committed with weitzman Aug 18, 2016
Showing with 106 additions and 13 deletions.
  1. +8 −6 commands/core/
  2. +9 −6 docs/
  3. +66 −0 docs/
  4. +17 −1 drush.api.php
  5. +6 −0 mkdocs.yml
@@ -591,14 +591,16 @@ function drush_config_import_validate() {
- * Presently, the only configuration storage filter that is supported
- * is the 'CoreExtensionFilter'. If other use cases arise that are
- * not supported by Drupal's configuration override system, then we
- * could add a hook here via drush_command_invoke_all('drush_storage_filters');
- *
- * See:
+ * Return storage filters to alter config import and export.
function drush_config_get_storage_filters() {
+ return drush_command_invoke_all('drush_storage_filters');
+ * Implements hook_drush_storage_filters().
+ */
+function config_drush_storage_filters() {
$result = array();
$module_adjustments = drush_get_option('skip-modules');
if (!empty($module_adjustments)) {
@@ -15,7 +15,7 @@ values, and how to make more complex changes.
It is not necessary to alter the configuration system values to
make simple value changes to configuration variables, as this may be
-done by the configuration override system.
+done by the [configuration override system](
The configuration override system allows you to change configuration
values for a given instance of a site (e.g. the development server) by
@@ -24,11 +24,6 @@ For example, to change the name of a local development site:
$config['']['name'] = 'Local Install of Awesome Widgets, Inc.';
-If you wish to change configuration values in code rather than in
-your settings.php file, it is also possible to alter configuration
-values in module hooks. See the [configuration override system](
-documentation for details.
Note that the configuration override system is a Drupal feature, not
a Drush feature. It should be the preferred method for changing
configuration values on a per-environment basis; however, it does not
@@ -56,3 +51,11 @@ will not cause it to be disabled again. Similarly, if you make changes
to configuration on the development environment and export them, then
the devel module will not be listed in the exports.
+## More Complex Adjustments
+Drush allows more complex changes to the configuration data to be made
+via the configuration filter mechanism. In order to do this, you must
+write some code inside a Drush extension.
+See [Drupal Configuration Filtering]( for more information
+on how to do this.
@@ -0,0 +1,66 @@
+# Filtering Drupal Configuration
+When exporting and importing configuration from and to a Drupal 8 site,
+Drush provides a mechanism called the Configuration Filter system which
+allows configuration values to be altered during import and export, allowing
+you to vary your configuration by environment. The --skip-modules option
+in the config-import and config-export commands is implemented with a
+configuration filter. For more complex uses, you will need to write some
+custom code.
+## Other Alternatives
+The Drupal Configuration system provides the capability to [add configuration
+overrides from modules]( Configuration
+overrides should be provided from a module override when possible. Implementing
+an override via a Drush extension is convenient in situations where you would
+like to be able to pass values in to the configuration filter via a Drush
+commandline option.
+## Filtering Drupal Configuration with Drush
+Instructions on writing a Drush extension to filter Drupal configuration follows.
+### Getting started
+The first thing that you will need to do is set up a Drush extension
+to hold your storage filter hook. See the example
+[example sandwich commandfile](../examples/ for
+details; note, however, that it is not necessary for your commandfile
+to implement hook_drush_command(), or any other hook besides the storage
+filter hook.
+You will need a composer.json file as well, in order to define where
+your StorageFilter class is defined. Make sure that Drush and your
+custom commandfile are required from the composer.json file of any
+Drupal site that you plan on using your filter with.
+### Implementing the Storage Filter Hook
+When Drush imports or exports configuration, it gives all Drush
+extensions a chance to hook this process by way of the hook
+hook_drush_storage_filters. The implementation of this hook,
+in the file, would look like this:
+function MYFILTER_drush_storage_filters() {
+ $result = array();
+ $my_option = drush_get_option('my-option');
+ if (!empty($my_option)) {
+ $result[] = new MyConfigurationFilter($my_option);
+ }
+ return $result;
+With this hook in place, MyConfigurationFilter will become part of
+the import / export process.
+### Implementing a Storage Filter
+It is necessary to implement a class that implements
+Your class only needs to implement the two methods defined there,
+filterRead() and filterWrite(), to make whichever alterations to configuration
+you need during the export and import operations, respectively. For
+an example class that implements StorageFilter, see the
@@ -14,7 +14,7 @@ function hook_drush_command() {
- * All drush commands are invoked in a specific order, using
+ * All Drush commands are invoked in a specific order, using
* drush-made hooks, very similar to the Drupal hook system. See drush_invoke()
* for the actual implementation.
@@ -420,6 +420,22 @@ function hook_drush_invoke_alter($modules, $hook) {
+ * Storage filters alter the .yml files on disk after a config-export or before
+ * a config-import. See `drush topic docs-config-filter` and config_drush_storage_filters().
+ */
+function hook_drush_storage_filters() {
+ $result = array();
+ $module_adjustments = drush_get_option('skip-modules');
+ if (!empty($module_adjustments)) {
+ if (is_string($module_adjustments)) {
+ $module_adjustments = explode(',', $module_adjustments);
+ }
+ $result[] = new CoreExtensionFilter($module_adjustments);
+ }
+ return $result;
* @} End of "addtogroup hooks".
@@ -21,3 +21,9 @@ pages:
- Command Authoring:
- Bootstrap:
- Context system:
+ - Filtering Drupal configuration:
+theme: readthedocs
+site_author: ""
+include_search: true
+#use_directory_urls: false

0 comments on commit 11ed42f

Please sign in to comment.