MappingTransformer integrates Mapper into Porter to support data transformations using Mapping objects. A full discussion of Mapper is beyond the scope of this document but the linked repository contains comprehensive documentation. MappingTransformer builds on Mapper by providing a powerful mapping strategy called SubImport.

The SubImport strategy provides a way to join data sets together. A mapping may contain any number of sub-imports, each of which may receive a different ImportSpecification. A sub-import causes Porter to begin a new import operation and thus supports all import options without limitation, including importing from different providers and applying a separate mapping to each sub-import.

SubImport(ImportSpecification|callable $specificationOrCallback)

1. $specificationOrCallback – Either an ImportSpecification instance or callable that returns such an instance.

The following example imports MyImportSpecification and copies the foo field from the input data into the output mapping. Next it performs a sub-import using MyDetailsSpecification and stores the result in the details key of the output mapping.

$records = $porter->import(
    (new MyImportSpecification)
        ->setMapping(new AnonymousMapping([
            'foo' => new Copy('foo'),
            'details' => new SubImport(MyDetailsSpecification),
        ]))
);

The following example is the same as the previous except MyDetailsSpecification now requires an identifier that is copied from details_id present in the input data. This is only possible using a callback since we cannot inject strategies inside specifications.

$records = $porter->import(
    (new MyImportSpecification)
        ->setMapping(new AnonymousMapping([
            'foo' => new Copy('foo'),
            'details' => new SubImport(
                function (array $record) {
                    return new MyDetailsSpecification($record['details_id']);
                }
            ),
        ]))
);