www.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 identifies 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  * @code
  33  * process:
  34  *   bar:
  35  *     plugin: static_map
  36  *     source: foo
  37  *     map:
  38  *       from: to
  39  *       this: that
  40  * @endcode
  41  *
  42  * If the value of the source property foo was "from" then the value of the
  43  * destination property bar will be "to". Similarly "this" becomes "that".
  44  * static_map can do a lot more than this: it supports a list of source
  45  * properties. This is super useful in module-delta to machine name conversions.
  46  *
  47  * @code
  48  * process:
  49  *   id:
  50  *     plugin: static_map
  51  *       source:
  52  *         - module
  53  *         - delta
  54  *        map:
  55  *          filter:
  56  *            0: filter_html_escape
  57  *            1: filter_autop
  58  *            2: filter_url
  59  *            3: filter_htmlcorrector
  60  *            4: filter_html_escape
  61  *          php:
  62  *            0: php_code
  63  * @endcode
  64  *
  65  * If the value of the source properties module and delta are "filter" and "2"
  66  * respectively, then the returned value will be "filter_url". By default, if a
  67  * value is not found in the map, an exception is thrown.
  68  *
  69  * When static_map is used to just rename a few things and leave the others, a
  70  * "bypass: true" option can be added. In this case, the source value is used
  71  * unchanged, e.g.:
  72  *
  73  * @code
  74  * process:
  75  *   bar:
  76  *     plugin: static_map
  77  *     source: foo
  78  *       map:
  79  *         from: to
  80  *         this: that
  81  *       bypass: TRUE
  82  * @endcode
  83  *
  84  * If the value of the source property "foo" is "from" then the returned value
  85  * will be "to", but if the value of "foo" is "another" (a value that is not in
  86  * the map) then the source value is used unchanged so the returned value will
  87  * be "from" because "bypass" is set to TRUE.
  88  *
  89  * @code
  90  * process:
  91  *   bar:
  92  *     plugin: static_map
  93  *     source: foo
  94  *       map:
  95  *         from: to
  96  *         this: that
  97  *       default_value: bar
  98  * @endcode
  99  *
 100  * If the value of the source property "foo" is "yet_another" (a value that is
 101  * not in the map) then the default_value is used so the returned value will
 102  * be "bar".
 103  *
 104  * @see \Drupal\migrate\Plugin\MigrateProcessInterface
 105  *
 106  * @MigrateProcessPlugin(
 107  *   id = "static_map"
 108  * )
 109  */
 110 class StaticMap extends ProcessPluginBase {
 111
 112   /**
 113    * {@inheritdoc}
 114    */
 115   public function transform($value, MigrateExecutableInterface $migrate_executable, Row $row, $destination_property) {
 116     $new_value = $value;
 117     if (is_array($value)) {
 118       if (!$value) {
 119         throw new MigrateException('Can not lookup without a value.');
 120       }
 121     }
 122     else {
 123       $new_value = [$value];
 124     }
 125     $new_value = NestedArray::getValue($this->configuration['map'], $new_value, $key_exists);
 126     if (!$key_exists) {
 127       if (array_key_exists('default_value', $this->configuration)) {
 128         if (!empty($this->configuration['bypass'])) {
 129           throw new MigrateException('Setting both default_value and bypass is invalid.');
 130         }
 131         return $this->configuration['default_value'];
 132       }
 133       if (empty($this->configuration['bypass'])) {
 134         throw new MigrateSkipRowException();
 135       }
 136       else {
 137         return $value;
 138       }
 139     }
 140     return $new_value;
 141   }
 142
 143 }