Fast Map

• What is it ?
• Installation
• Usage
  • Building an ArrayMapper
  • Building a ListMapper
  • Building a CollectionMapper
  • Building an ObjectMapper
  • Building a ConditionalMapper

A mapping is an operation that associates each element of a source of data into a new format of the same data. By this operation, it is possible to transform the way the data is represented.

What is it ?

The FastMap plugin aims at integrating mappers into the Pipeline stack.

FastMap Plugin consists of two components, each with a different purpose.

The php-etl/fast-map component

This component is in charge of representing the Abstract Mapping Tree, and transforming it into compiled PHP code. This compiled PHP code is the actual code that will do the mapping, in an optimized way.

Abstract Mapping Tree

The abstract mapping tree is a representation of the mapping to apply to your data, in order to transform its representation. It is an internal representation build for a computer to understand how it will have to change the data representation during the mapping operation.

The php-etl/fast-map-config component

This component allows you to configure your mapper according to the type of data you want to input.

If you need to config your mappers, we advise you to use the yml config which will generate a php code usable by the fast-map-config. This code will then be converted into a machine code that can be used by the fast map package.

Installation

composer require php-etl/fast-map-plugin:'*'

Usage

Building an ArrayMapper

To write a mapping to an array, you must use the `map option.

fastmap:
  append: true # Optional. Merges this step's output into the previous step's result.
  map:
  # ...

Next, you need to specify the field you are going to map to and assign a value to it.

The field option is based on the PropertyAccess component of Symfony. You must therefore respect this [field_name] naming format.

To assign a value to your field, you can choose between several options :

Simple options

• copy : This option also uses the PropertyAccess component of Symfony and allows you to retrieve a value from an array and copy it.
• expression : This expression uses the Expressionlanguage component of Symfony component and allows you to write your own expressions.
• constant : This option allows you to write directly the value of your field

fastmap:
  map:
    - field: '[sku]'
      copy: '[sku]'
    - field: '[title]'
      expression: 'input["sku"] ~" | "~ input["name"]'
    - field: '[staticValue]'
      constant: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit. Curabitur mollis efficitur justo, id facilisis elit venenatis et.'
    # ...

Advanced options

• map : see the configuration
• list : see the configuration
• collection : see the configuration
• object : see the configuration

fastmap: 
  map: 
    - field: '[foo]'
      expression: 'input'
      map:
        - field: '[bar]'
          copy: '[bar]'
    - field: '[foo]'
      expression: 'input'
      list:
        - field: '[bar]'
          copy: '[bar]'
    - field: '[descriptions]'
      class: 'Pipeline\Usage'
      expression: 'input["foo"]'
      object:
        - field: 'usage'
          expression: '"Usage: " ~ input["usage"]'
        - field: 'warning'
          copy: '[warning]'
        - field: 'notice'
          copy: '[notice]'
    - field: '[messages]'
      class: 'Foo\DTO\Messages'
      expression: 'input'
      collection:
        - field: 'usage'
          expression: '"Usage: " ~ input["usage"]'
        - field: 'warning'
          copy: '[warning]'
        - field: 'notice'
          copy: '[notice]'

Building a ListMapper

To write a mapping to a list, you must use the list option, which will always be accompanied by the expression option.

• expression : allows you to write an expression which will be used in the mapping.

fastmap:
  expression: 'input'
  list:
    - field: '[bar]'
      copy: '[bar]'

Building a CollectionMapper

To write a mapping to a collection of objects, you must use the collection option, which will always be accompanied by the class and expression options.

• class : determines the class to use in the mapping.
• expression : allows you to write an expression which will be used in the mapping.

fastmap:
  class: 'Foo\DTO\Messages'
  expression: 'input'
  collection:
    - field: 'usage'
      expression: '"Usage: " ~ input["usage"]'
    - field: 'warning'
      copy: '[warning]'
    - field: 'notice'
      copy: '[notice]'

Warning: Unlike an ArrayMapper, here the field must not be between [...].

See Reading from objects.

Building an ObjectMapper

To write a mapping to an object, you must use the object option, which will always be accompanied by the options class and expression.

• class : determines the class to be used in the mapping.
• expression : allows you to write an expression that will be used in the mapping.

fastmap:
  class: 'Foo\DTO\Product'
  expression: 'input'
  object:
    - field: 'sku'
      copy: '[sku]'

Warning: Unlike an ArrayMapper, here the field must not be between [...].

See Reading from objects.

Building a ConditionalMapper

To write a list of mappers that will only execute if a condition is met, you must use the conditional option, under which you can declare multiple Array (map) or Object (object) mappers, each protected by a condition.

The behaviour is similar to if ... else if ..., meaning only 1 of the mappers will be executed.

fastmap:
  conditional:
    - condition: 'keyExists("sku", input)'
      append: true # Optional. Merges this step's output into the previous step's result.
      map:
        # ...
    - condition: 'keyExists("identifier", input)'
      append: true
      object:
        # ...