Small improvements for the Data Mappers docs

[mpdude]

I just had a brief chat with @webmozart at the #EUFOSSA #FOSSHackathons event regarding the documentation of data mappers. I was unaware that they had finally made it into the docs 🎉.

A valueable hint that Bernhard gave me was that based on his experience, in 80% percent of the cases data mappers are stateless. In that case, you can implement the data mapping in the form type itself – just make the FormType implement DataMapperInterface and use setDataMapper($this) in the buildForm() method. That may simplify your code, as you do not need to keep a second class around that is used in one place only. Yet, you can still test the code in the same way as before as the methods are available through the interface.

When the Data Mapper is stateful and needs access to services and/or form data, you should also be able to create the instance from within the FormType. Honestly, I'd have to experiment with this a little to sketch out the code (or do you have an example ready somewhere on slides or talks, Bernhard?).

[webmozart]

🍾

I'd use the example given in the docs for the stateless mapper:

// src/Form/Type/ColorType.php
namespace App\Form\Type;

use App\Painting\Color;
use Symfony\Component\Form\AbstractType;
use Symfony\Component\Form\DataMapperInterface;
use Symfony\Component\Form\Exception\UnexpectedTypeException;
use Symfony\Component\Form\Extension\Core\Type\IntegerType;
use Symfony\Component\Form\FormBuilderInterface;
use Symfony\Component\Form\FormInterface;
use Symfony\Component\OptionsResolver\OptionsResolver;

final class ColorType extends AbstractType implements DataMapperInterface
{
    public function buildForm(FormBuilderInterface $builder, array $options)
    {
        $builder
            ->add('red', IntegerType::class, [
                // enforce the strictness of the type to ensure the constructor
                // of the Color class doesn't break
                'empty_data' => '0',
            ])
            ->add('green', IntegerType::class, [
                'empty_data' => '0',
            ])
            ->add('blue', IntegerType::class, [
                'empty_data' => '0',
            ])
            ->setDataMapper($this);
    }

    public function configureOptions(OptionsResolver $resolver)
    {
        // when creating a new color, the initial data should be null
        $resolver->setDefault('empty_data', null);
    }

    /**
     * @param Color|null $data
     */
    public function mapDataToForms($data, $forms)
    {
        // there is no data yet, so nothing to prepopulate
        if (null === $data) {
            return;
        }

        // invalid data type
        if (!$data instanceof Color) {
            throw new UnexpectedTypeException($data, Color::class);
        }

        /** @var FormInterface[] $forms */
        $forms = iterator_to_array($forms);

        // initialize form field values
        $forms['red']->setData($data->getRed());
        $forms['green']->setData($data->getGreen());
        $forms['blue']->setData($data->getBlue());
    }

    public function mapFormsToData($forms, &$data)
    {
        /** @var FormInterface[] $forms */
        $forms = iterator_to_array($forms);

        // as data is passed by reference, overriding it will change it in
        // the form object as well
        // beware of type inconsistency, see caution below
        $data = new Color(
            $forms['red']->getData(),
            $forms['green']->getData(),
            $forms['blue']->getData()
        );
    }
}

For the stateful one, I'd build onto the stateless one for didactic reasons. Maybe pass in a fixed opacity from the outside?

// src/Form/Type/ColorType.php
namespace App\Form\Type;

use App\Form\DataMapper\ColorMapper;
use Symfony\Component\Form\AbstractType;
use Symfony\Component\Form\Extension\Core\Type\IntegerType;
use Symfony\Component\Form\FormBuilderInterface;
use Symfony\Component\OptionsResolver\OptionsResolver;

final class ColorType extends AbstractType
{
    public function buildForm(FormBuilderInterface $builder, array $options)
    {
        $builder
            ->add('red', IntegerType::class, [
                // enforce the strictness of the type to ensure the constructor
                // of the Color class doesn't break
                'empty_data' => '0',
            ])
            ->add('green', IntegerType::class, [
                'empty_data' => '0',
            ])
            ->add('blue', IntegerType::class, [
                'empty_data' => '0',
            ])
            ->setDataMapper(new ColorMapper($options['opacity']));
    }

    public function configureOptions(OptionsResolver $resolver)
    {
        // when creating a new color, the initial data should be null
        $resolver->setDefault('empty_data', null);
        $resolver->setDefault('opacity', 1);
    }
}

// src/Form/DataMapper/ColorMapper.php
namespace App\Form\DataMapper;

use App\Painting\Color;
use Symfony\Component\Form\DataMapperInterface;
use Symfony\Component\Form\Exception\UnexpectedTypeException;
use Symfony\Component\Form\FormInterface;

final class ColorMapper implements DataMapperInterface
{
    private $opacity;
    
    public function __construct(float $opacity)
    {
        $this->opacity = $opacity;
    }

    /**
     * @param Color|null $data
     */
    public function mapDataToForms($data, $forms)
    {
        // there is no data yet, so nothing to prepopulate
        if (null === $data) {
            return;
        }

        // invalid data type
        if (!$data instanceof Color) {
            throw new UnexpectedTypeException($data, Color::class);
        }

        /** @var FormInterface[] $forms */
        $forms = iterator_to_array($forms);

        // initialize form field values
        $forms['red']->setData($data->getRed());
        $forms['green']->setData($data->getGreen());
        $forms['blue']->setData($data->getBlue());
    }

    public function mapFormsToData($forms, &$data)
    {
        /** @var FormInterface[] $forms */
        $forms = iterator_to_array($forms);

        // as data is passed by reference, overriding it will change it in
        // the form object as well
        // beware of type inconsistency, see caution below
        $data = new Color(
            $forms['red']->getData(),
            $forms['green']->getData(),
            $forms['blue']->getData(),
            $this->opacity
        );
    }
}

[OskarStark]

I like the examples, just a small comment from my side: if I am right this addition to the documentation should target 3.4 branch and therefore “AppBundle” namespace should be used instead of “App”

[javiereguiluz]

@OskarStark yes, you are right ... but that's an internal detail for mergers.

@wouterj will you have some time to update these examples? Thanks!

[wouterj]

I'll take a look this week