Process plugin: iterator

Last updated on
21 June 2017

This documentation is incomplete. Add more information.

The iterator process plugin allows processing of a list of associative arrays (for simple lists see handling multiple values). Often source data will logically include multiple-value properties as associative arrays. For example, for filter formats on Drupal 6, the filters property contains a list of filters belonging to that format, identified by a numeric delta (a delta of 2 indicates the URL filter, a delta of 1 indicates automatic breaking, etc.):

source: Array
(
    [format] => 1
    [name] => Filtered HTML
...
    [filters] => Array
        (
            [0] => Array
                (
                    [module] => filter
                    [delta] => 2
                    [weight] => 0
                )
            [1] => Array
                (
                    [module] => filter
                    [delta] => 0
                    [weight] => 1
                )
...

The iterator will take these arrays one at a time and run its own process over each one:

process:
  filters:
    plugin: iterator
    source: filters
    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

So, plugin: iterator and source: filters means we take each array element [0], [1], etc. in the source filters field, and apply the static_map plugin to it. We take the first ([0]) array:

Array
(
    [module] => filter
    [delta] => 2
    [weight] => 0
)

The map source keys are module and delta, so in the map key, since the [module] value is filter, we index the array using the delta value of 2 and arrive at filter_url as our value - this will be the first value in the array assigned to the destination filters. Similarly, we will take the 0 value for the delta in the second array to generate a second value of filter_html_escape.

There's one more problem that needs to be solved: often the key of the arrays need to be changed. In this case, the new id property needs to be the key. It'd be possible to just add key: "@id" to the iterator process but that would require special casing the key property and somehow escape it when there is actually a destination called key. Instead, it is moved out of the process and key is in the configuration of iterator itself:

process:
  filters:
    plugin: iterator
    source: filters
    key: "@id"
    process:
      id:
        plugin: static_map

The process pipeline for key is special in two ways: first, it runs after the normal process is done. Because of this, key: "@key" is also valid. Second, the pipeline does not start with NULL but the value of the current key. This way, the value of key can come from the other properties or the current key. For the latter, omit the source from the first plugin in the pipeline for key.

An example of the input and output data is attached.