aleph1.co.uk Git - yaffs-website/blob - web/core/modules/migrate/src/Plugin/migrate/process/StaticMap.php

   1 <?php
   2
   3 namespace Drupal\migrate\Plugin\migrate\process;
   4
   5 use Drupal\Component\Utility\NestedArray;
   6 use Drupal\migrate\ProcessPluginBase;
   7 use Drupal\migrate\MigrateException;
   8 use Drupal\migrate\MigrateExecutableInterface;
   9 use Drupal\migrate\Row;
  10 use Drupal\migrate\MigrateSkipRowException;
  11
  12 /**
  13  * Changes the source value based on a static lookup map.
  14  *
  15  * Maps the input value to another value using an associative array specified in
  16  * the configuration.
  17  *
  18  * Available configuration keys:
  19  * - source: The input value - either a scalar or an array.
  20  * - map: An array (of 1 or more dimensions) that defines the mapping between
  21  *   source values and destination values.
  22  * - bypass: (optional) Whether the plugin should proceed when the source is not
  23  *   found in the map array, defaults to FALSE.
  24  *   - TRUE: Return the unmodified input value, or another default value, if one
  25  *     is specified.
  26  *   - FALSE: Throw a MigrateSkipRowException.
  27  * - default_value: (optional) The value to return if the source is not found in
  28  *   the map array.
  29  *
  30  * Examples:
  31  *
  32  * If the value of the source property 'foo' is 'from' then the value of the
  33  * destination property bar will be 'to'. Similarly 'this' becomes 'that'.
  34  * @code
  35  * process:
  36  *   bar:
  37  *     plugin: static_map
  38  *     source: foo
  39  *     map:
  40  *       from: to
  41  *       this: that
  42  * @endcode
  43  *
  44  * The static_map process plugin supports a list of source properties. This is
  45  * useful in module-delta to machine name conversions. In the example below,
  46  * value 'filter_url' is returned if the source property 'module' is 'filter'
  47  * and the source property 'delta' is '2'.
  48  * @code
  49  * process:
  50  *   id:
  51  *     plugin: static_map
  52  *     source:
  53  *       - module
  54  *       - delta
  55  *     map:
  56  *       filter:
  57  *         0: filter_html_escape
  58  *         1: filter_autop
  59  *         2: filter_url
  60  *         3: filter_htmlcorrector
  61  *         4: filter_html_escape
  62  *       php:
  63  *         0: php_code
  64  * @endcode
  65  *
  66  * When static_map is used to just rename a few values and leave the others
  67  * unchanged, a 'bypass: true' option can be used. See the example below. If the
  68  * value of the source property 'foo' is 'from', 'to' will be returned. If the
  69  * value of the source property 'foo' is 'another' (a value that is not in the
  70  * map), 'another' will be returned unchanged.
  71  * @code
  72  * process:
  73  *   bar:
  74  *     plugin: static_map
  75  *     source: foo
  76  *     map:
  77  *       from: to
  78  *       this: that
  79  *     bypass: TRUE
  80  * @endcode
  81  *
  82  * A default value can be defined for all values that are not included in the
  83  * map. See the example below. If the value of the source property 'foo' is
  84  * 'yet_another' (a value that is not in the map), 'bar' will be returned.
  85  * @code
  86  * process:
  87  *   bar:
  88  *     plugin: static_map
  89  *     source: foo
  90  *     map:
  91  *       from: to
  92  *       this: that
  93  *     default_value: bar
  94  * @endcode
  95  *
  96  * If your source data has boolean values as strings, you need to use single
  97  * quotes in the map. See the example below.
  98  * @code
  99  * process:
 100  *   bar:
 101  *     plugin: static_map
 102  *     source: foo
 103  *     map:
 104  *       'TRUE': to
 105  * @endcode
 106  *
 107  * Mapping from a string which contains a period is not supported. A custom
 108  * process plugin can be written to handle this kind of a transformation.
 109  * Another option which may be feasible in certain use cases is to first pass
 110  * the value through the machine_name process plugin.
 111  *
 112  * @see https://www.drupal.org/project/drupal/issues/2827897
 113  * @see \Drupal\migrate\Plugin\MigrateProcessInterface
 114  *
 115  * @MigrateProcessPlugin(
 116  *   id = "static_map"
 117  * )
 118  */
 119 class StaticMap extends ProcessPluginBase {
 120
 121   /**
 122    * {@inheritdoc}
 123    */
 124   public function transform($value, MigrateExecutableInterface $migrate_executable, Row $row, $destination_property) {
 125     $new_value = $value;
 126     if (is_array($value)) {
 127       if (!$value) {
 128         throw new MigrateException('Can not lookup without a value.');
 129       }
 130     }
 131     else {
 132       $new_value = [$value];
 133     }
 134     $new_value = NestedArray::getValue($this->configuration['map'], $new_value, $key_exists);
 135     if (!$key_exists) {
 136       if (array_key_exists('default_value', $this->configuration)) {
 137         if (!empty($this->configuration['bypass'])) {
 138           throw new MigrateException('Setting both default_value and bypass is invalid.');
 139         }
 140         return $this->configuration['default_value'];
 141       }
 142       if (empty($this->configuration['bypass'])) {
 143         throw new MigrateSkipRowException();
 144       }
 145       else {
 146         return $value;
 147       }
 148     }
 149     return $new_value;
 150   }
 151
 152 }