www.aleph1.co.uk Git - yaffs-website/blob - vendor/drush/drush/docs/config-filter.md

   1 # Filtering Drupal Configuration
   2
   3 When exporting and importing configuration from and to a Drupal 8 site,
   4 Drush provides a mechanism called the Configuration Filter system which
   5 allows configuration values to be altered during import and export, allowing
   6 you to vary your configuration by environment.  The --skip-modules option
   7 in the config-import and config-export commands is implemented with a
   8 configuration filter.  For more complex uses, you will need to write some
   9 custom code.
  10
  11 ## Other Alternatives
  12
  13 The Drupal Configuration system provides the capability to [add configuration
  14 overrides from modules](https://www.drupal.org/node/1928898).  Configuration
  15 overrides should be provided from a module override when possible.  Implementing
  16 an override via a Drush extension is convenient in situations where you would
  17 like to be able to pass values in to the configuration filter via a Drush
  18 commandline option.
  19
  20 ## Filtering Drupal Configuration with Drush
  21
  22 Instructions on writing a Drush extension to filter Drupal configuration follows.
  23
  24 ### Getting started
  25
  26 The first thing that you will need to do is set up a Drush extension
  27 to hold your storage filter hook.  See the example
  28 [example sandwich commandfile](../examples/sandwich-drush.inc) for
  29 details; note, however, that it is not necessary for your commandfile
  30 to implement hook_drush_command(), or any other hook besides the storage
  31 filter hook.
  32
  33 You will need a composer.json file as well, in order to define where
  34 your StorageFilter class is defined.  Make sure that Drush and your
  35 custom commandfile are required from the composer.json file of any
  36 Drupal site that you plan on using your filter with.
  37
  38 ### Implementing the Storage Filter Hook
  39
  40 When Drush imports or exports configuration, it gives all Drush
  41 extensions a chance to hook this process by way of the hook
  42 hook_drush_storage_filters.  The implementation of this hook,
  43 in the file MYFILTER.drush.inc, would look like this:
  44 ```
  45 function MYFILTER_drush_storage_filters() {
  46   $result = array();
  47   $my_option = drush_get_option('my-option');
  48   if (!empty($my_option)) {
  49     $result[] = new MyConfigurationFilter($my_option);
  50   }
  51   return $result;
  52 }
  53 ```
  54 With this hook in place, MyConfigurationFilter will become part of
  55 the import / export process.
  56
  57 ### Implementing a Storage Filter
  58
  59 It is necessary to implement a class that implements
  60 [StorageFilter](https://github.com/drush-ops/drush/blob/master/lib/Drush/Config/StorageFilter.php).
  61 Your class only needs to implement the two methods defined there,
  62 filterRead() and filterWrite(), to make whichever alterations to configuration
  63 you need during the export and import operations, respectively.  For
  64 an example class that implements StorageFilter, see the
  65 [CoreExtensionFilter](https://github.com/drush-ops/drush/blob/master/lib/Drush/Config/CoreExtensionFilter.php)
  66 class.