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