Property Mapping¶

Example Usage¶

The most simple usage is to convert simple types to different simple types, i.e. converting a numeric string to a float number:

// $propertyMapper is of class TYPO3\FLOW3\Property\PropertyMapper
$result = $propertyMapper->convert('12.5', 'float');
// $result == (float)12.5

This is of course a really conceived example, as the same result could be archieved by just casting the numeric string to a floating point number.

Our next example goes a bit further and shows how we can use the Property Mapper to convert an array of data into a domain model:

/**
 * @FLOW3\Entity
 */
class TYPO3\MyPackage\Domain\Model\Person {
        /**
         * @var string
         */
        protected $name;

        /**
         * @var \DateTime
         */
        protected $birthDate;

        /**
         * @var TYPO3\MyPackage\Domain\Model\Person
         */
        protected $mother;
        // ... furthermore contains getters and setters for the above properties.
}

$inputArray = array(
        'name' => 'John Fisher',
        'birthDate' => '1990-11-14T15:32:12+00:00'
);
$person = $propertyMapper->convert($inputArray, 'TYPO3\MyPackage\Domain\Model\Person');

// $person is a newly created object of type TYPO3\MyPackage\Domain\Model\Person
// $person->name == 'John Fisher'
// $person->birthDate is a DateTime object with the correct date set.

We’ll first use a simple input array:

$input = array(
  'name' => 'John Fisher',
  'birthDate' => '1990-11-14T15:32:12+00:00'
);

After calling $propertyMapper->convert($input, 'TYPO3\MyPackage\Domain\Model\Person'), we receive an ew object of type ``Person which has $name set to John Fisher, and $birthDate set to a DateTime object of the specified date. You might now wonder how the PropertyMapper knows how to convert DateTime objects and Person objects? The answer is: It does not know that. However, the PropertyMapper calls specialized Type Converters which take care of the actual conversion.

In our example, three type converters are called:

• First, to convert ‘John Fisher’ to a string (required by the annotation in the domain model), a StringConverter is called. This converter simply passes through the input string, without modification.
• Then, a DateTimeConverter is called, whose responsibility is to convert the input string into a valid DateTime object.
• At the end, the Person object still needs to be built. For that, the PersistentObjectConverter is responsible. It creates a fresh Person object, and sets the $name and $birthDate properties which were already built using the type converters above.

This example should illustrate that property mapping is a recursive process, and the PropertyMappers task is exactly to orchestrate the different TypeConverters needed to build a big, compound object.

The PersistentObjectConverter has some more features, as it supports fetching objects from the persistence layer if an identity for the object is given. Both the following inputs will result in the corresponding object to be fetched from the persistence layer:

$input = '14d20100-9d70-11e0-aa82-0800200c9a66';
// or:
$input = array(
  '__identity' => '14d20100-9d70-11e0-aa82-0800200c9a66'
);

$person = $propertyMapper->convert($input, 'MyCompany\MyPackage\Domain\Model\Person');
// The $person object with UUID 14d20100-9d70-11e0-aa82-0800200c9a66 is fetched from the persistence layer

In case some more properties are specified in the array (besides __identity), the submitted properties are modified on the fetched object. These modifications are not automatically saved to the database at the end of the request, you need to pass such an instance to update on the corresponding repository to persist the changes.

So, let’s walk through a more complete input example:

$input = array(
  '__identity' => '14d20100-9d70-11e0-aa82-0800200c9a66',
  'name' => 'John Doe',
  'mother' => 'efd3b461-6f24-499d-97bc-309dfbe01f05'
);

In this case, the following steps happen:

• The Person``object with identity ``14d20100-9d70-11e0-aa82-0800200c9a66 is fetched from persistence.
• The $name of the fetched $person object is updated to John Doe
• As the $mother property is also of type Person, the PersistentObjectConverter is invoked recursively. It fetches the Person object with UUID efd3b461-6f24-499d-97bc-309dfbe01f05, which is then set as the $mother property of the original person.

Here, you see that we can also set associations using the Property Mapper.

Configuring the Conversion Process¶

It is possible to configure the conversion process by specifying a PropertyMappingConfiguration as third parameter to PropertyMapper::convert(). If no PropertyMappingConfiguration is specified, the PropertyMappingConfigurationBuilder automatically creates a default PropertyMappingConfiguration.

In most cases, you should use the PropertyMappingConfigurationBuilder to create a new PropertyMappingConfiguration, so that you get a convenient default configuration:

// $propertyMappingConfigurationBuilder instanceof TYPO3\FLOW3\Property\PropertyMappingConfigurationBuilder
$propertyMappingConfiguration = $propertyMappingConfigurationBuilder->build();
// modify $propertyMappingConfiguration

$propertyMapper->convert($source, $targetType, $propertyMappingConfiguration);

The following configuration options exist:

• setMapping($sourcePropertyName, $targetPropertyName) can be used to rename properties.

  Example: If the input array contains a property lastName, but the accordant property in the model is called $givenName, the following configuration performs the renaming:

  $propertyMappingConfiguration->setMapping('lastName', 'givenName');
  

• setTypeConverter($typeConverter) can be used to directly set a type converter which should be used. This disables the automatic resolving of type converters.

• setTypeConverterOption($typeConverterClassName, $optionKey, $optionValue) can be used to set type converter specific options.

  Example: The DateTimeConverter supports a configuration option for the expected date format:

  $propertyMappingConfiguration->setTypeConverterOption(
          'TYPO3\FLOW3\Property\TypeConverter\DateTimeConverter',
          \TYPO3\FLOW3\Property\TypeConverter\DateTimeConverter::CONFIGURATION_DATE_FORMAT,
          'Y-m-d'
  );
  

• setTypeConverterOptions($typeConverterClassName, array $options) can be used to set multiple configuration options for the given TypeConverter. This overrides all previously set configuration options for the TypeConverter.

• allowProperties($propertyName1, $propertyName2, ...) specifies the allowed property names which should be converted on the current level.

• allowAllProperties() allows all properties on the current level.

• allowAllPropertiesExcept($propertyName1, $propertyName2) effectively inverts the behavior: all properties on the current level are allowed, except the ones specified as arguments to this method.

All the configuration options work only for the current level, i.e. all of the above converter options would only work for the toplevel type converter. However, it is also possible to specify configuration options for lower levels, using forProperty($propertyPath). This is best shown with the example from the previous section.

The following configuration sets a mapping on the top level, and furthermore configures the DateTime converter for the birthDate property:

$propertyMappingConfiguration->setMapping('fullName', 'name');
$propertyMappingConfiguration
        ->forProperty('birthDate')
        ->setTypeConverterOption(
                'TYPO3\FLOW3\Property\TypeConverter\DateTimeConverter',
                \TYPO3\FLOW3\Property\TypeConverter\DateTimeConverter::CONFIGURATION_DATE_FORMAT,
                'Y-m-d'
        );

forProperty() also supports more than one nesting level using the dot notation, so writing something like forProperty('mother.birthDate') is possible.

array(
  'username' => 'mynewuser',
  'role' => '5bc42c89-a418-457f-8095-062ace6d22fd'
);

array(
  'username' => 'mynewuser',
  'role' => array(
    'name' => 'superuser',
    'admin' => 1
  )
);

Reference of TypeConverters¶

The Inner Workings of the Property Mapper¶

The Property Mapper applies the following steps to convert a simple type to an object. Some of the steps will be described in detail afterwards.

1. Figure out which type converter to use for the given source - target pair.

2. Ask this type converter to return the child properties of the source data (if it has any), by calling getSourceChildPropertiesToBeConverted() on the type converter.

3. For each child propery, do the following:

   1. Ask the type converter about the data type of the child property, by calling getTypeOfChildProperty() on the type converter.
   2. Recursively invoke the PropertyMapper to build the child object from the input data.

4. Now, call the type converter again (method convertFrom()), passing all (already built) child objects along. The result of this call is returned as the final result of the property mapping process.

On first sight, the steps might seem complex and difficult, but they account for a great deal of flexibility of the property mapper. Automatic resolving of type converters