DataTransferObject.md

Data Transfer Object configuration

Mandatory annotations

To recognize the Data Transfer Object, the ParamConverter requires the class annotation @DTO to be set or the class to be tagged as app.data_transfer_object. Here, we only use the DTO annotation but you can find more information about the tag here.

To correctly extract the appropriate values to the variables, the ParamConverter requires to explicitly declare the type using the Type assertion of the Symfony validation component.

The DataTransferParamConverter also allows to map a collection of object as well using the Symfony assertion All.

The following example uses the annotation style configuration:

/**
 * @DTO
 */
final class DummyDataTransferObject
{
    /**
     * @Assert\Type("App\Entity\YourEntity")
     */
    public $property;
    
    /**
     * @Assert\Type("\DateTime")
     */
    public $anyDate;
    
    /**
     * @Assert\All(
     *     @Assert\Type("App\Entity\AnotherEntity");
     * )
     */
    public $collectionOfEntity
}

MapTo annotation

The MapTo annotation allows to map the content request to a specific field of an Entity. For instance, if the entity DummyEntity has a field keyname, you can get it using this field by adding the MapTo annotation.

Here is an example of this annotation:

/**
 * @Assert\Type("App\Entity\DummyEntity")
 *
 * @MapTo("keyname")
 */
public $dummyEntity;

Field annotation

In case the input does not match the name of the property, you can explicitly bind a input key to a specific property using the Field annotation.

Here is an example of this annotation:

/**
 * @Assert\Type("App\Entity\User")
 *
 * @Field("user_id")
 */
public $user;

Validation

UniqueEntityData

The UniqueEntityData constraint checks if the selected DTO fields are unique for the target entity.

In the following example, the validator will check if a DummyEntity with the same property1 and property2 fields exists.

/**
 * @DTO
 *
 * @UniqueEntityData(
 *     fields={"property1", "property2"},
 *     entityClass="App\Entity\DummyEntity"
 * )
 */
final class DummyDataTransferObject
{
    public $property1;
    
    public $property2;
}

An entity can be accepted using the except parameter which will tolerate to break the unicity restriction if the found entity is the same as the one in the except. The except option uses the Expression language, so this reffers to the DTO and this.targetEntity reffers to the value of the $targetEntity property.

/**
 * @DTO
 *
 * @UniqueEntityData(
 *     fields={"property1", "property2"},
 *     entityClass="App\Entity\DummyEntity",
 *     except="this.targetEntity"
 * )
 */
final class DummyDataTransferObject
{
    /**
     * @Assert\Type("App\Entity\DummyEntity")
     */
    public $targetEntity;
    
    public $property1;
    
    public $property2;
}