Add storage filter hook for benefit of config_split and similar contrib/custom projects.

This brings back commit 7322efc.

Author: bircher

commands/core/config.drush.inc

@@ -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: https://github.com/drush-ops/drush/pull/1522
+ * 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)) {

docs/config-exporting.md

@@ -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](https://www.drupal.org/node/1928898).
 
 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['system.site']['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](https://www.drupal.org/node/1928898)
-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](config-filter.md) for more information
+on how to do this.

docs/config-filter.md

@@ -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](https://www.drupal.org/node/1928898).  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/sandwich-drush.inc) 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 MYFILTER.drush.inc, 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 
+[StorageFilter](https://github.com/drush-ops/drush/blob/master/lib/Drush/Config/StorageFilter.php).
+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
+[CoreExtensionFilter](https://github.com/drush-ops/drush/blob/master/lib/Drush/Config/CoreExtensionFilter.php)
+class.

drush.api.php

@@ -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".
  */

mkdocs.yml

@@ -21,3 +21,9 @@ pages:
   - Command Authoring: commands.md
   - Bootstrap: bootstrap.md
   - Context system: context.md
+  - Filtering Drupal configuration: config-filter.md
+theme: readthedocs
+site_author: ""
+repo_url: https://github.com/drush-ops/drush
+include_search: true
+#use_directory_urls: false