Process plugin: static map

Last updated on
20 June 2017

The static_map source plugin allows looking up a value based on a map specified in the configuration.

Example:

process:
  bar:
    plugin: static_map
    source: foo
    map:
      from: to
      this: that

If the value of the source property foo was from then the value of the destination property bar will be to. Similarly this becomes that.

static_map can do a lot more than this: it supports a list of source properties. This is super useful in module-delta to machine name conversions.

process:
  id:
    plugin: static_map
    source:
      - module
      - delta
    map:
      filter:
        0: filter_html_escape
        1: filter_autop
        2: filter_url
        3: filter_htmlcorrector
        4: filter_html_escape
      php:
        0: php_code

If the value of the source properties module and delta are filter and 2 respectively, then the value of the destination id will be filter_url.

By default, if a value is not found in the map, an exception is thrown. This is desirable in the above example. When static_map is used to just rename a few things and leave the others, a bypass: true option can be added. In this case, the source value is used unchanged.

Also, a default_value can be provided.

Example:

process:
  bar:
    plugin: static_map
    source: foo
    map:
      from: to
      this: that
    default_value: bar

If the lookup fails, this value is used instead. Note that using the default value plugin after would not work as the pipeline has a value at this point: the value of the source specified for the static_map.

Key gotchas

YAML Booleans

Using an unquoted string which represents a boolean value in YAML (various forms of yes/no/true/false/on/off) as a key in your map will use that boolean value rather than the string itself as your key, which is almost certainly not what you want. Be sure to quote any such strings to use them as strings.

Doesn't work:

process:
  bar:
    plugin: static_map
    source: foo
    map:
      # This works as if it were '1: to'.
      TRUE: to

Does work:
 

process:
  bar:
    plugin: static_map
    source: foo
    map:
      'TRUE': to

Periods in key names

Mapping from a string which contains a period does not work at all - this:

process:
  bar:
    plugin: static_map
    source: foo
    map:
      'Version 3.0': version_3_0

will give the error

exception 'Drupal\Core\Config\ConfigValueException' with message 'Version 3.0 key contains a dot which is not supported.' in /var/www/example/docroot/core/lib/Drupal/Core/Config/ConfigBase.php:211

There is an existing issue #2827897: static_map process plugin does not work with periods in keys to address this. In the meantime, a custom process plugin would be needed to map source data containing periods if they could not be removed by a previous process plugin like machine_name (which will run the value over the transliteration service, lowercases it, replaces anything that's not a number or a letter with an underscore and removes duplicate underscores):

process:
  bar:
    -
      plugin: machine_name
      source: foo
    -
      plugin: static_map
      map:
        'version_3_0': version_3_0