Как использовать преобразователи данных¶

Простой пример: Преобразование строковых тегов из ввода пользователя в массив¶

Представьте, что у вас есть форма задачи (task) с типом тегов text:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

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

use App\Entity\Task;
use Symfony\Component\Form\FormBuilderInterface;
use Symfony\Component\OptionsResolver\OptionsResolver;
use Symfony\Component\Form\Extension\Core\Type\TextType;

// ...
class TaskType extends AbstractType
{
    public function buildForm(FormBuilderInterface $builder, array $options)
    {
        $builder->add('tags', TextType::class);
    }

    public function configureOptions(OptionsResolver $resolver)
    {
        $resolver->setDefaults(array(
            'data_class' => Task::class,
        ));
    }

    // ...
}

Внутренне, tags хранятся в этом массиве, но отображаются пользователю, как обычная строка, разделяемая запятой, чтобы облегчить их редактирование.

Это идеальное время, чтобы присоединить пользовательский преобразователь данных к полю tags. Легчевсего это сделать с помощью класса CallbackTransformer:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30

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

use Symfony\Component\Form\CallbackTransformer;
use Symfony\Component\Form\FormBuilderInterface;
use Symfony\Component\Form\Extension\Core\Type\TextType;
// ...

class TaskType extends AbstractType
{
    public function buildForm(FormBuilderInterface $builder, array $options)
    {
        $builder->add('tags', TextType::class);

        $builder->get('tags')
            ->addModelTransformer(new CallbackTransformer(
                function ($tagsAsArray) {
                    // преобразовать массив в строку
                    return implode(', ', $tagsAsArray);
                },
                function ($tagsAsString) {
                    // преобразовать строку обратно в массив
                    return explode(', ', $tagsAsString);
                }
            ))
        ;
    }

    // ...
}

CallbackTransformer берёт две функции обратного вызова в качестве аргументов. Первый преобразует первоначальное значение в формат, который будет использован для отображения поля. Второй делает обратное - он преобразует отправленное значение обратно в формат, который вы увидите в своём коде.

Вы также можете добавить преобразователь во время добавления поля, слегка изменив формат:

1
2
3
4
5
6
7

use Symfony\Component\Form\Extension\Core\Type\TextType;

$builder->add(
    $builder
        ->create('tags', TextType::class)
        ->addModelTransformer(...)
);

Более сложный пример: Преобразование номера проблемы в сущность проблемы¶

Скажем, у вас есть отношение многие-к-одному между сущностью Задачи (task) и сущностью Проблемы (issue) (т.е. каждая задача имеет необязательный внешний ключ к относящейся к ней проблеме). Добавление окна списка со всеми возможными проблемами может быть очень долгим и долго загружаться. Вместо этого, вы рашаете, что вы хотите добавить текстовое окно, где пользователь может просто вводить номер проблемы.

Начните с установки текстового поля, как обычно:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

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

use App\Entity\Task;
use Symfony\Component\Form\Extension\Core\Type\TextareaType;
use Symfony\Component\Form\Extension\Core\Type\TextType;

// ...
class TaskType extends AbstractType
{
    public function buildForm(FormBuilderInterface $builder, array $options)
    {
        $builder
            ->add('description', TextareaType::class)
            ->add('issue', TextType::class)
        ;
    }

    public function configureOptions(OptionsResolver $resolver)
    {
        $resolver->setDefaults(array(
            'data_class' => Task::class,
        ));
    }

    // ...
}

Хорошее начало! Но если бы вы остановились здесь и отправили форму, то свойство задачи issue было бы строкой (например, "55"). Как вы можете преобразовать это в сущность Issue при отправке?

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65

// src/Form/DataTransformer/IssueToNumberTransformer.php
namespace App\Form\DataTransformer;

use App\Entity\Issue;
use Doctrine\ORM\EntityManagerInterface;
use Symfony\Component\Form\DataTransformerInterface;
use Symfony\Component\Form\Exception\TransformationFailedException;

class IssueToNumberTransformer implements DataTransformerInterface
{
    private $em;

    public function __construct(EntityManagerInterface $em)
    {
        $this->em = $em;
    }

    /**
     * Трансформирует объект (проблему) в строку (цифру).
     *
     * @param  Issue|null $issue
     * @return строку
     */
    public function transform($issue)
    {
        if (null === $issue) {
            return '';
        }

        return $issue->getId();
    }

    /**
     * Transforms a string (number) to an object (issue).
     *
     * @param  string $issueNumber
     * @return Issue|null
     * @throws TransformationFailedException if object (issue) is not found.
     */
    public function reverseTransform($issueNumber)
    {
        // нет номера проблемы? Это необязательно, так что всё хорошо
        if (!$issueNumber) {
            return;
        }

        $issue = $this->em
            ->getRepository('AppBundle:Issue')
            // запрос проблемы по этому id
            ->find($issueNumber)
        ;

        if (null === $issue) {
            // вызывает ошибку валидации
            // это сообщение не отображается пользователю
            // смотрите опцию invalid_message
            throw new TransformationFailedException(sprintf(
                'An issue with number "%s" does not exist!',
                $issueNumber
            ));
        }

        return $issue;
    }
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34

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

use App\Form\DataTransformer\IssueToNumberTransformer;
use Symfony\Component\Form\Extension\Core\Type\TextareaType;
use Symfony\Component\Form\Extension\Core\Type\TextType;

// ...
class TaskType extends AbstractType
{
    private $transformer;

    public function __construct(IssueToNumberTransformer $transformer)
    {
        $this->transformer = $transformer;
    }

    public function buildForm(FormBuilderInterface $builder, array $options)
    {
        $builder
            ->add('description', TextareaType::class)
            ->add('issue', TextType::class, array(
                // validation message if the data transformer fails
                'invalid_message' => 'That is not a valid issue number',
            ));

        // ...

        $builder->get('issue')
            ->addModelTransformer($this->transformer);
    }

    // ...
}

1
2
3
4

// например, где-то в контроллере
$form = $this->createForm(TaskType::class, $task);

// ...

1
2
3
4

// ЭТО НЕПРАВИЛЬНО - ПРЕОБРАЗОВАТЕЛЬ БУДЕТ ПРИМЕНЁН КО ВСЕЙ ФОРМЕ
// см. пример выше для правильного кода
$builder->add('issue', TextType::class)
    ->addModelTransformer($transformer);

Создание повторно используемого поля issue_selector¶

В примере выше, вы применяли преобразователь к нормальному полю text. Но если вы часто делаете это преобразование, то может быть лучше создать пользовательский тип поля. который делает это автоматически.

Для начала, создайте пользовательский класс типа поля:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35

// src/Form/IssueSelectorType.php
namespace App\Form;

use App\Form\DataTransformer\IssueToNumberTransformer;
use Doctrine\Common\Persistence\ObjectManager;
use Symfony\Component\Form\AbstractType;
use Symfony\Component\Form\FormBuilderInterface;
use Symfony\Component\OptionsResolver\OptionsResolver;

class IssueSelectorType extends AbstractType
{
    private $transformer;

    public function __construct(IssueToNumberTransformer $transformer)
    {
        $this->transformer = $transformer;
    }

    public function buildForm(FormBuilderInterface $builder, array $options)
    {
        $builder->addModelTransformer($this->transformer);
    }

    public function configureOptions(OptionsResolver $resolver)
    {
        $resolver->setDefaults(array(
            'invalid_message' => 'The selected issue does not exist',
        ));
    }

    public function getParent()
    {
        return TextType::class;
    }
}

Отлично! Он будет действоваь и отображать, как текстовое поле (getParent()), но будет автоматически иметь преобразователь данных и хорошее значение по умолчанию для опции invalid_message.

Если вы используете автомонтирование и автоконфигурацию, вы можете незамедлительно начать использование формы:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19

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

use App\Form\DataTransformer\IssueToNumberTransformer;
use Symfony\Component\Form\Extension\Core\Type\TextareaType;
// ...

class TaskType extends AbstractType
{
    public function buildForm(FormBuilderInterface $builder, array $options)
    {
        $builder
            ->add('description', TextareaType::class)
            ->add('issue', IssueSelectorType::class)
        ;
    }

    // ...
}

О преобразователях модели и просмотра¶

В примере выше, преобразователь был использован как "модель". На самом деле, существует два разных вида преобразователей и три разных типа лежащих в основе данных.

В любой форме, три разных типа данных - это:

1. Данные модели - Это данные в формате, используемом в вашем приложении (например, объект Issue). Если вы вызовете Form::getData() или Form::setData(), вы имеете дело с данными "модели".
2. Данные нормы - Это нормализированная версия ваших данных и она зачастую совпадает с данными "модели" (но не в нашем примере). Обычно они не используются напрямую.
3. Данные просмотра - Это формат, который используется для заполнения самих полей формы. Это также формат, в котором пользователь будет отправлять данные. Когда вы вызываете Form::submit($data), $data имеет формат данных "просмотра".

Два разных типа преобразователей помогают конвертировать из и в каждый из этих типов данных:

Преобразователи модели:

• transform(): "данные модели" => "данные нормы"
• reverseTransform(): "данные нормы" => "данные модели"

Преобразователи просмотра:

• transform(): "данные нормы" => "данные просмотра"
• reverseTransform(): "данные просмотра" => "данные нормы"

То, какой преобразователь вам нужен, зависит от ситуации.

Чтобы использовать преобразователь просмотра, вызовите addViewTransformer().

Так зачем использовать преобразователь модели?¶

В этом примере, поле - это поле text, а текстовое поле всегда должно быть простым скалярным форматом в форматах "нормы" и "просмотра". По этой причине, наиболее подходящим преобразователем был преобразователь "модели" (который конвертирует из/в формата нормы - строки номера проблемы - в формат модели - объект проблемы).

Разница между преобразователями тонкая, и вы всегда должны думать о том, какими на самом деле должны быть данные "нормы" для поля. Например, данные "нормы" для поля text - это строка, но для поля date - это объект DateTime.