TYPO3 Flow Base Distribution

• Goal
• Wanted Features
• Basic Interface
• PropertyMappingConfiguration
• Default Property Mapping Configuration
• Type Converter examples
  • Entity Type Converter
  • Date Type Converter
  • SplObjectStorage/ArrayCollection Type Converter
• Error Handling
• Validation / Partial Validation
• Naming
• Further work

Goal¶

The property mapper maps simple types to Objects. (Hence, we (for now) drop the Object to Object support, although this could be added later)

The Property Mapper maps all values present in $source to $target (or a subset thereof) (right now, it requires a list of properties to be mapped, and if $source[$propertyName] does not exist, an error is thrown)

• We try to strip down the Property Mapper, and make it extensible instead.

Wanted Features¶

• Support for Object Converters:
  • array / ArrayObject / SplObjectStorage
  • DateTime use case
  • File Upload (Resource objects)
• Partial Validation should be supported
• Property Merging should be supported (pass in existing object as base-object)
• Better error handling in case target property is not found (right now, NULL returned)
• Mapping should be configurable
• Secure by default

Basic Interface¶

1map(mixed $source, string $targetType, PropertyMappingConfigurationInterface $propertyMappingConfiguration = NULL)

• $source can be:
  • all simple values (integer, string, ...)
  • ARRAY
  • an Object implementing ArrayAccess
  • We will drop support for arbitary objects through ObjectAccess::isPropertyGettable (for now)
  • else EXCEPTION

• $target is the classname on which the value should be mapped to (or a simple type)

Pseudocode:

 1map(...) {
 2    if ($propertyMappingConfiguration === NULL) {
 3        $propertyMappingConfiguration = $this->buildDefaultPropertyMappingConfiguration();
 4    }
 5    $propertyMappingConfiguration->setTargetType($targetType); // Just a convenience shorthand method
 6    $this->doMapping(....);
 7}
 8
 9protected function doMapping(mixed $source, $propertyMappingConfiguration) {
10    $typeConverter = $this->somehowDetermineTypeConverter(); // TODO, see below
11
12    $object = $typeConverter->convertFrom($source, $propertyMappingConfiguration);
13
14    foreach ($typeConverter->getPropertyNames($source) as $sourcePropertyName) {
15        $targetPropertyName = $propertyMappingConfiguration->getTargetPropertyName($sourcePropertyName);
16        if (!$propertyMappingConfiguration->shouldMap($targetPropertyName)) continue;
17
18        $mappedPropertyValue = $this->doMapping($source[$sourcePropertyName], $propertyMappingConfiguration->getConfigurationFor($targetPropertyName));
19
20        $typeConverter->setResultInTarget($target, $targetPropertyName, $mappedPropertyValue);
21    }
22    return $object;
23}

• The property mapper only delegates the actual mapping to Type Converters.
• Type converters expose the following information:
  • Applicable source types
  • The target type the converter can convert to
  • A priority
• The used type converter is determined as follows:
  • If a TypeConverter is set inside the current propertyMappingConfiguration, this one is taken.
  • Else, we do the following:
    

     1$typeConvertersWhichCanHandleSourceType = // first, we pick all TypeConverters
     2        // which can handle $sourceType, and put it into an
     3        // associative array where KEY is the target class name of the converter
     4$classNamesInInheritanceHierarchy = // $targetType combined with all superclasses
     5        // and interfaces, ordered from the inside out (so the $targetType
     6        // is the first element in the list)
     7
     8foreach ($classNamesInInheritanceHierarchy as $singleTargetClassName) {
     9    if (isset($typeConvertersWhichCanHandleSourceType[$singleTargetClassName])) {
    10        return the type converter from $typeConvertersWhichCanHandleSourceType[$singleTargetClassName] with highest priority
    11    }
    12}
    13// Exception if no type converter found
    

• Type Converters have to adhere to the following interface:
  

  1public function convertFrom($source, $propertyMappingConfiguration);
  2public function getPropertyNames($source);
  3public function setMappingResultInTarget($target, $propertyName, $mappingResult);
  

• In case a type converter does not want to handle a certain element (for whatever reason), he can throw an DontWantToHandleThisInputException inside convertFrom. Then, the next Type converter according to the above rules is taken.

• Furthermore, the Property Mapper can handle renaming of properties, see the method getTargetPropertyName in the PropertyMappingConfigurationInterface

PropertyMappingConfiguration¶

 1interface PropertyMappingConfigurationInterface {
 2
 3    /**
 4     * @return string
 5     */
 6    public function getTargetType();
 7
 8    /**
 9     * @return TRUE if the given propertyName should be mapped
10     */
11    public function shouldMap($propertyName);
12
13    /**
14     * @return PropertyMappingConfigurationInterface the property mapping configuration for the given PropertyName.
15     */
16    public function getConfigurationFor($propertyName);
17
18    /**
19     * @return string property name of target; can be used to rename properties from source to target.
20     */
21    public function getTargetPropertyName($sourcePropertyName);
22
23    /**
24     * @return mixed configuration value for the specific $typeConverterClassName. Can be used by Type Converters to fetch converter-specific configuration
25     */
26    public function getConfigurationValue($typeConverterClassName, $key);
27}

This interface will have an implementing class "PropertyMappingConfiguration", looking like the following:

 1class PropertyMappingConfiguration implements PropertyMappingConfigurationInterface {
 2    public function setTargetType($type);
 3    public function setMapping($sourcePropertyName, $targetPropertyName);
 4    public function setConfigurationValue($typeConverter, $key, $value);
 5
 6    /**
 7     * Returns the default configuration for all sub-objects, ready to be modified
 8     */
 9    public function defaultSubConfiguration();
10
11    /**
12     * Returns the configuration for the specific property path, ready to be modified
13     */
14    public function at($propertyPath);
15
16}

This API can then be used as follows:

• To globally disable the modification of entities by the property mapper:
  

  1$propertyMappingConfiguration->setConfigurationValue('F3....\EntityConverter', 'modificationAllowed', FALSE);

• To disable the modification of sub-entities of the root element:
  

  1$propertyMappingConfiguration->defaultSubConfiguration()->setConfigurationValue('F3....\EntityConverter', 'modificationAllowed', FALSE);

• To enable the creation of sub-objects inside a certain element:
  

  1$propertyMappingConfiguration->at('subobject1.subsubobject2')->setConfigurationValue('F3....\EntityConverter', 'creationAllowed', TRUE);

Furthermore, there will be a subclass ControllerPropertyMappingConfiguration, which has some convenience methods implemented such that people can program against a type-safe API:

1class ControllerPropertyMappingConfiguration extends PropertyMappingConfiguration {
2    public function allowCreationOfSubObjectsAt($position) {
3        $this->at($position)->setConfigurationValue('F3....\EntityConverter', 'creationAllowed', TRUE);
4    }
5    public function allowModificationOfSubObjectsAt($position) {
6        $this->at($position)->setConfigurationValue('F3....\EntityConverter', 'modificationAllowed', TRUE);
7    }
8}

Default Property Mapping Configuration¶

• The default property mapping configuration for the top level should configure the Entity Type Converter to modify and create new objects
• The property mapping configuration further down the hierarchy should configure the Entity Type Converter to not modify and not create objects.
• The above two things are safety precautions for the user.
• This boils down to the following code:

1 $propertyMappingConfiguration->setConfigurationValue('F3....\EntityConverter', 'modificationAllowed', TRUE);
2 $propertyMappingConfiguration->defaultSubConfiguration()->setConfigurationValue('F3....\EntityConverter', 'modificationAllowed', FALSE);

Type Converter examples¶

Here follow some examples of type converters, to see the concept more easily:

Entity Type Converter¶

• Input Type: String and Array
• Output Type: Object
• Priority: low

 1public function convertFrom($source, $propertyMappingConfiguration) {
 2    if (is_string($source)) {
 3        if (/* is UUID */) {
 4            // create and return object
 5        } else {
 6            // Exception
 7        }
 8    }
 9
10    if (isset($source['__identity'])) {
11        $target = // fetch from persistence
12        if (count($source) > 1) {
13            if ($propertyMappingConfiguration->getConfigurationValue('F3\....\EntityConverter', 'modificationAllowed') !== TRUE) {
14                // throw exception
15            }
16            $target = clone $target;
17        }
18    } else {
19        if ($propertyMappingConfiguration->getConfigurationValue('F3\....\EntityConverter', 'creationAllowed') !== TRUE) {
20            // throw exception
21        }
22        $target = // new
23    }
24
25    return $target;
26}
27
28public function getPropertyNames($source) {
29        if (is_string($source)) return array();
30        return all $source property names, *except* __identity;
31}
32
33public function setMappingResultInTarget($target, $propertyName, $mappingResult) {
34        // Set Property through Object Access
35}

Date Type Converter¶

• Input Type: String and Array
• Output Type: DateTime
• Priority: low

 1public function convertFrom($source, $propertyMappingConfiguration) {
 2    new DateTime($source); // or more advanced...
 3};
 4public function getPropertyNames() {
 5    return array();
 6}
 7public function setMappingResultInTarget($target, $propertyName, $mappingResult) {
 8    // empty, as it is never called
 9}

SplObjectStorage/ArrayCollection Type Converter¶

• Input Type: Array
• Output Type: SplObjectStorage
• Priority: low

 1public function convertFrom($source, $propertyMappingConfiguration) {
 2    return new \SplObjectStorage();
 3};
 4public function getPropertyNames($source) {
 5    return array_keys($source);
 6}
 7
 8public function setMappingResultInTarget($target, $propertyName, $mappingResult) {
 9    $target->attach($value);
10}

Error Handling¶

• Instead of outputting human-readable error messages, the property mapper will throw exceptions in case of errors. For things like mandatory properties, specific validators should be used.

Validation / Partial Validation¶

• The property mapper will not execute any validators for the given objects.
• However, it should return a list of mapped properties. This list can be used later, such that the ObjectValidator only needs to validate changed properties.

Naming¶

Object Converters will be superseded by this concept, and thrown away.

We suggest to change the naming in the following way:

• PropertyMapper -> TypeMapper / ObjectMapper?
• Object Converter -> Type Converter

Further work¶

• This concept could be extended lateron to work with arbitrary input objects, not just simple types. However, one would then need a way to deal with object inheritance hierarchies on the source side as well.
• Extend the concept such that Half-ready objects as $target are also supported; but we would use an explicit new API function for this:
  

  1merge(mixed $source, object $targetObject, PropertyMappingConfigurationInterface $propertyMappingConfiguration = NULL)