Using a Command as DTO to populate Symfony Form

[webdevilopers]

@beberlei shows a good example on how to use this approach here:
http://whitewashing.de/2012/08/22/building_an_object_model__no_setters_allowed.html

With the following code you can add the EditPostCommand to the data_class of the EditPostType form:

<?php
class EditPostCommand
{
    public $id;
    public $headline;
    public $text;
    public $tags = array();
}

<?php
class PostController
{
    public function editAction(Request $request)
    {
        $post = $this->findPostViewModel($request->get('id'));

        // This could need some more automation/generic code
        $editPostCommand           = new EditPostCommand();
        $editPostCommand->id       = $request->get('id');
        $editPostCommand->headline = $post->headline;
        $editPostCommand->text     = $post->text;
        $editPostCommand->tags     = $post->tags;

        // here be the form framework handling...
        $form = $this->createForm(new EditPostType(), $editPostCommand);
        $form->bind($request);

        if (!$form->isValid()) {
            // invalid, show errors
        }

        // here we invoke the model, finally, through the service layer
        $this->postService->edit($editPostCommand);
    }
}

But it seems like Commands should be regarded immutable too which means the properties should not be public. Of course Symfony Form needs at least these to populate the Command.

@matthiasnoback has an interesting solution for this Symfony Form Use Case:
https://github.com/matthiasnoback/convenient-immutability

A Groovy example by @bodiam:
http://www.jworks.nl/2011/08/26/friday-repost-groovys-immutable-pitfalls/

General discussion:
https://groups.google.com/forum/#!msg/dddinphp/a5ielXU3EZg/qEoi5ppWAgAJ

Is there any approach how we could use the Command with Symfony Form if the properties were private?

Maybe using the empty_data callback on the Command / DTO and a static method as suggested by @webmozart:
http://whitewashing.de/2012/08/22/building_an_object_model__no_setters_allowed.html#comment-1091314235

[matthiasnoback]

The Convenient Immutability library is not 100% serious actually. The thing with immutability is that it isn't really needed in this case. You won't be tempted to modify the object, right? And you won't need to pass it around, you just hand it over to a command handler of some sorts.
Mutable objects are mainly a danger when they can be modified by other parts of the application. If you're the one working on that application, considering immutability a good thing, you don't really need actual immutability anymore ;) Or you use my library, which will at least prevent anyone less smart than you from modifying previously populated fields.

[webdevilopers]

Thanks @matthiasnoback ! I agree - the only modification comes from the form happening once and the the Command is passed to the Handler.

The only thing I have to find our now is how much smarter I am! ;)

[yvoyer]

To add more sugar to the command, maybe we could add a static factory method EditPostCommand::fromPost (Post $post): EditPostCommand. That way instead of changing the controller when adding a new property to the command for the edit, it could be wrapped directly in the command.

[webdevilopers]

I do something similar @yvoyer to pre-populate a Symfony Form for Orders if an optional Offer already exists:

        $placeOrderCommand = ($offer instanceof Offer)
            ? PlaceOrderCommand::fromOffer($offer)
            : new PlaceOrderCommand($customer->getId());

[chrisguitarguy]

The Convenient Immutability library is not 100% serious actually. The thing with immutability is that it isn't really needed in this case. You won't be tempted to modify the object, right? And you won't need to pass it around, you just hand it over to a command handler of some sorts.

100% agree. I leave public properties in commands for the sake of forms quite a bit. But I do provider getters on those same commands and treat them as immutable in their handlers.

$form->bind($request);

Unrelated, but this should be...

$this->createForm(EditPostType::class, $editPostCommand);
$form->handleRequest($request)
if ($form->isValid()) {
  // ...
}

Bind is deprecated (and removed in Symfony 3.x), and handleRequest is the new way to submit the form with a symfony request object.

[rommsen]

my 2 cents:

We are currently in the process of moving away from having mutable command objects (and from using them as a data-source for Symfony forms)

Reasons (all imho of course):

• Similiar to entities I will never get into a situation where my object is in an inconsistent state. But what does inconsistent state mean in case of a simple DTO with no behavior? For me it means that every client consuming the DTO is guaranteed to have access to everything the DTO is making publicly available. If I use (and populate) public properties it is not guaranteed that the value is set or not null or that the type matches my expectation (expect to be an array but is populated with a string)
• Testing of command handlers gets much easier / less bloated. Of course you already have this if you work with getters, because then you can setup simple test doubles.
• Using commands as data source for a form will bring you in a situation where you are tempted to have something in your command just because it is more convenient in your form. When you are not doing this you will never need to think about forms when creating the commands in the first place
• Of course the last point boils down to a single responsibility of your object. I want my commands to have one reason for existence: Being handled in a command handler. And if I change my commands I don't want to be bothered with changing my form structure.

But how do you get the data to your forms and how do you create a command with form data?

We use DataMappers provided by the Form Library (read this awesome article by @webmozart)

First of all we use the third and not the second parameter to give data to the form

 // second parameter is empty
$form = $this->createForm(ReportingDataType::class, [], ['job' => $job]);

Then we define which data is needed by the form

public function configureOptions(OptionsResolver $resolver)
{
    ...
    $resolver->setRequired(['job']);
}

We can implement the DataMapperInterface and set it to the form itself

class ReportingDataType extends AbstractType implements DataMapperInterface
{
    private $job;

    public function buildForm(FormBuilderInterface $builder, array $options)
    {
        $this->job = $options['job'];
        // ... 
        $builder ->setDataMapper($this)

and we implement the mapping methods

public function mapDataToForms($data, $forms)
{
    $getIds = function (Questionnaire $questionnaire) {
        return $questionnaire->getId();
    };
    $reportingData = $this->job->getReportingData();
    $forms = iterator_to_array($forms);
    $forms['inherit_reporting_data']->setData($this->job->inheritsReportingData());
    $forms['questionnaires_for_jobs']->setData(array_map($getIds, $reportingData->getQuestionnairesForJobs()));
    $forms['questionnaires_for_slots']->setData(array_map($getIds, $reportingData->getQuestionnairesForSlots()));
}

public function mapFormsToData($forms, &$data)
{
    $forms = iterator_to_array($forms);
    $data = new ChangeJobReportingDataCommand(
        $this->job->getId(),
        $forms['inherit_reporting_data']->getData(),
        $forms['questionnaires_for_jobs']->getData(),
        $forms['questionnaires_for_slots']->getData()
    );
}

finally we can normally validate and dispatch our command:

$form->handleRequest($this->request);
if ($form->isValid()) {
    $this->dispatchCommand($form->getData());

What do we win?

• colocation of our form definition with the process of transforming our data source to the form and your our to the result (the command) (colocate as much as it is reasonable, see react and inline css as another example).
• we have an explicit mapping of this process
• our command is not dependent on form fields anymore (except for validation of course, but you can use http://symfony.com/doc/current/reference/forms/types/form.html#property-path if needed
• refactoring of our public command api is much simpler, because we can use "find usages" (if you use phpstorm). This is not possible when everything is done by form magic.

What do we lose:

• form magic (which is actually a win imho)

RFC 😄

[webdevilopers]

Well that's a very interesting approach @rommsen . Havn't seen it before.

Did you ever experience problems using your Data Transformers with let's say Symfony FormEvents?
What do your commands look like regarding "Validation" e.g. Constraints?

[rommsen]

Hey @webdevilopers. Sorry had some busy days.

Concerning validation: We are using commands with a payload array and not with multiple properties. To validate this we use the collection constraint. The cool thing is, that it allows us to define, whether it is allowed to have fields, that are not mentioned in the validations or not.

/**
     * @var array
     * @AssertThat\Collection(
     *     fields = {
     *         "id" = {
     *             @AssertThat\NotBlank(),
     *             @AssertThat\NotNull()
     *         },
     *         "phone_home" = @Assert\PhoneNumber(defaultRegion="DE"),
     *         "phone_mobile" = @Assert\PhoneNumber(defaultRegion="DE"),
     *         "phone_business" = @Assert\PhoneNumber(defaultRegion="DE"),
     *         "fax" = @Assert\PhoneNumber(defaultRegion="DE"),
     *         "second_phone_home" = @Assert\PhoneNumber(defaultRegion="DE"),
     *         "email" = {
     *             @AssertThat\NotBlank(),
     *             @AssertThat\Email()
     *         }
     *     },
     *     allowExtraFields = true
     * )
     */
    protected $payload;

Concerning form events: As I said we are currently in the process of refactoring towards the described workflow. We have yet to refactor a form with events attached. But I dont think there are big problems. That said, I have to remark that since we started to move towards a task based UI, our forms tend to become MUCH smaller. They don't have as much edge cases as they had when we where mainly doing huge CRUD forms (i.e. we need form events very seldom).

[rommsen]

Here is a current amendment:

With the described approach we had a problem, when the form creates a Command VO which itself needed a VO for its creation. If the needed VO is never created (e.g. a user is not selecting a value in a choice list), the Command can not be created, and we can not use the normal validation.

To solve this problem we used DataTransformers (inline, i.e. CallbackTransformers) which throw a TransformationException, when the VO was not created. With this approach we are able to map the exception directly to the not validationg form field. Example

...

class CancellationType extends AbstractType implements DataMapperInterface
{
    /**
     * @var CancellationId
     */
    private $cancellationId;

    public function buildForm(FormBuilderInterface $builder, array $options)
    {
        $this->cancellationId = $options['cancellationId'];

        $builder
            ->setDataMapper($this) // maps form data to the resulting command
            ->add(
                'reason', ValueObjectChoiceType::class, [
                    'loader_callback' => function () {
                        return CancellationReason::all();
                    },
                    'label' => 'cancellation.reason',
                    'invalid_message' => 'validation.application.choose_value',
                    'allowClear' => true,
                ]
            )
            ->add('notice', NoticeType::class, [
                'label' => 'cancellation.notice',
            ]);

        // custom ModelTransformer which throws an Exception when the $value created by the 
        // form is not a VO (CancellationReason)
        // the form uses then the value form the 'invalid_message' option defined above
        $builder->get('reason')
            ->addModelTransformer(new CallbackTransformer(
                function ($value) {
                    return $value;
                },
                function ($value) {
                    if ($value instanceof CancellationReason) {
                        return $value;
                    }
                    throw new Exception\TransformationFailedException();
                }
            ));
    }

...

    public function mapFormsToData($forms, &$data)
    {
        $forms = iterator_to_array($forms);

        $reason = $forms['reason']->getData();
        $notice = $forms['notice']->getData();

        // needs to be checked because this method is called 
        // even when there was a TransformationException
        if ($reason === null || $notice === null) {
            return;
        }
        $data = BeginCancellation::withData($this->cancellationId,$reason,$notice );
    }
}

I have to say that I am very happy with this approach. Many people complain about all the magic in the form component (which is bad when not doing RAD) but it provides so many nice extension points. I think, when used correctly, it is a very good fit for building an application with DDD in mind.