#i', "\n", $originalDescription);
+ },
+ function ($submittedDescription) {
+ // remove most HTML tags (but not br,p)
+ $cleaned = strip_tags($submittedDescription, '
');
+
+ // transform any \n to real
+ return str_replace("\n", '
', $cleaned);
+ }
+ ));
+ }
+
+ // ...
+ }
+
+The ``CallbackTransformer`` takes to callback functions as arguments. The first transforms
+the original value into a format that'll be used to render the field. The second
+does the reverse: it transforms the submitted value back into the format you'll use
+in your code.
+
+.. tip::
+
+ The ``addModelTransformer()`` method accepts *any* object that implements
+ :class:`Symfony\\Component\\Form\\DataTransformerInterface` - so you can create
+ your own classes, instead of putting all the logic in the form (see the next section).
+
+You can also add the transformer, right when adding the field by changing the format
+slightly::
+
+ $builder->add(
+ $builder->create('description', 'textarea')
+ ->addModelTransformer(...)
+ );
+
+Harder Example: Transforming an Issue Number into an Issue Entity
+-----------------------------------------------------------------
+
+Say you have a many-to-one relation from the Task entity to an Issue entity (i.e. each
+Task has an optional foreign key to its related Issue). Adding a listbox with all
+possible issues could eventually get *really* long and take a long time to load.
+Instead, you decide you want to add a textbox, where the user can simply enter the
+issue number.
+
+Start by setting up the text field like normal::
+
+ // src/AppBundle/Form/TaskType.php
+
+ // ...
+ class TaskType extends AbstractType
+ {
+ public function buildForm(FormBuilderInterface $builder, array $options)
+ {
+ $builder
+ ->add('description', 'textarea')
+ ->add('issue', 'text');
+ }
+
+ public function setDefaultOptions(OptionsResolverInterface $resolver)
+ {
+ $resolver->setDefaults(array(
+ 'data_class' => 'AppBundle\Entity\Task'
+ ));
+ }
+
+ // ...
+ }
+
+Good start! But if you stopped here and submitted the form, the Task's ``issue``
+property would be a string (e.g. "55"). How can you transform this into an ``Issue``
+entity on submit?
+
Creating the Transformer
-------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+You could use the ``CallbackTransformer`` like earlier. But since this is a bit more
+complex, creating a new transformer class will keep the ``TaskType`` form class simpler.
-First, create an ``IssueToNumberTransformer`` class - this class will be responsible
-for converting to and from the issue number and the ``Issue`` object::
+Create an ``IssueToNumberTransformer`` class: it will be responsible for converting
+to and from the issue number and the ``Issue`` object::
// src/AppBundle/Form/DataTransformer/IssueToNumberTransformer.php
namespace AppBundle\Form\DataTransformer;
use AppBundle\Entity\Issue;
- use Doctrine\Common\Persistence\ObjectManager;
+ use Doctrine\Common\Persistence\EntityManager;
use Symfony\Component\Form\DataTransformerInterface;
use Symfony\Component\Form\Exception\TransformationFailedException;
class IssueToNumberTransformer implements DataTransformerInterface
{
- /**
- * @var ObjectManager
- */
- private $om;
+ private $entityManager;
- /**
- * @param ObjectManager $om
- */
- public function __construct(ObjectManager $om)
+ public function __construct(EntityManager $entityManager)
{
- $this->om = $om;
+ $this->entityManager = $entityManager;
}
/**
@@ -63,31 +183,36 @@ for converting to and from the issue number and the ``Issue`` object::
return '';
}
- return $issue->getNumber();
+ return $issue->getId();
}
/**
* Transforms a string (number) to an object (issue).
*
- * @param string $number
+ * @param string $issueNumber
* @return Issue|null
* @throws TransformationFailedException if object (issue) is not found.
*/
- public function reverseTransform($number)
+ public function reverseTransform($issueNumber)
{
- if (!$number) {
- return null;
+ // no issue number? It's optional, so that's ok
+ if (!$issueNumber) {
+ return;
}
- $issue = $this->om
+ $issue = $this->entityManager
->getRepository('AppBundle:Issue')
- ->findOneBy(array('number' => $number))
+ // query for the issue with this id
+ ->find($issueNumber)
;
if (null === $issue) {
+ // causes a validation error
+ // this message is not shown to the user
+ // see the invalid_message option
throw new TransformationFailedException(sprintf(
'An issue with number "%s" does not exist!',
- $number
+ $issueNumber
));
}
@@ -95,10 +220,15 @@ for converting to and from the issue number and the ``Issue`` object::
}
}
-.. tip::
+Just like in the first example, a transformer has two directions. The ``transform()``
+method is responsible for converting the data used in your code to a format that
+can be rendered in your form (e.g. an ``Issue`` object to its ``id``, a string).
+The ``reverseTransform()`` method does the reverse: it converts the submitted value
+back into the format you want (e.g. convert the ``id`` back to the ``Issue`` object).
- If you want a new issue to be created when an unknown number is entered, you
- can instantiate it rather than throwing the ``TransformationFailedException``.
+To cause a validation error, throw a :class:`Symfony\\Component\\Form\\Exception\\TransformationFailedException`.
+But the message you pass to this exception won't be shown to the user. You'll set
+that message with the ``invalid_message`` option (see below).
.. note::
@@ -107,142 +237,60 @@ for converting to and from the issue number and the ``Issue`` object::
an empty string, 0 for integers or 0.0 for floats).
Using the Transformer
----------------------
-
-As seen above our transformer requires an instance of an object manager. While for most
-use-cases it is sufficient to use the default entity manager, you will sometimes need
-to explicitly choose the one to use. To achieve this, you can use a factory::
-
- // src/AppBundle/Form/DataTransformer/IssueToNumberTransformerFactory.php
- namespace AppBundle\Form\DataTransformer;
-
- use Doctrine\Common\Persistence\ManagerRegistry;
-
- class IssueToNumberTransformerFactory
- {
- /**
- * @var ManagerRegistry
- */
- private $registry;
-
- public function __construct(ManagerRegistry $registry)
- {
- $this->registry = $registry;
- }
-
- public function create($om)
- {
- return new IssueToNumberTransformer($this->registry->getManager($om));
- }
- }
-
-.. configuration-block::
-
- .. code-block:: yaml
-
- services:
- app.issue_transformer_factory:
- class: AppBundle\Form\DataTransformer\IssueToNumberTransformerFactory
- arguments: ["@doctrine"]
- public: false
-
- app.type.task:
- class: AppBundle\Form\TaskType
- arguments: ["@app.issue_transformer_factory"]
- tags:
- - { name: form.type, alias: app_task }
-
- .. code-block:: xml
-
-
-
-
-
-
-
-
-
+~~~~~~~~~~~~~~~~~~~~~
- .. code-block:: php
-
- use Symfony\Component\DependencyInjection\Definition;
- use Symfony\Component\DependencyInjection\Reference;
- // ...
-
- $container
- ->setDefinition('app.issue_transformer_factory', new Definition(
- 'AppBundle\Form\DataTransformer\IssueToNumberTransformerFactory'
- ), array(
- new Reference('doctrine'),
- ))
- ->setPublic(false)
- ;
-
- $container
- ->setDefinition('app.type.task', new Definition(
- 'AppBundle\Form\TaskType'
- ), array(
- new Reference('app.issue_transformer_factory'),
- ))
- ->addTag('form.type', array('alias' => 'app_task'))
- ;
-
-Now that you have the capability to build the transformer with the desired object manager, you
-just need to create it from your issue field in some form.
+Next, you need to instantiate the ``IssueToNumberTransformer`` class from inside
+``TaskType`` and add it to the ``issue`` field. But to do that, you'll need an instance
+of the entity manager (because ``IssueToNumberTransformer`` needs this).
-You can also use transformers without creating a new custom form type
-by calling ``addModelTransformer`` (or ``addViewTransformer`` - see
-`Model and View Transformers`_) on any field builder::
+No problem! Just add a ``__construct()`` function to ``TaskType`` and force this
+to be passed in. Then, you can easily create and add the transformer::
// src/AppBundle/Form/TaskType.php
- namespace AppBundle\Form;
- use AppBundle\Form\DataTransformer\IssueToNumberTransformerFactory;
- use Symfony\Component\Form\FormBuilderInterface;
- use Symfony\Component\OptionsResolver\OptionsResolverInterface;
+ use AppBundle\Form\DataTransformer\IssueToNumberTransformer;
+ use Doctrine\Common\Persistence\EntityManager;
+ // ...
class TaskType extends AbstractType
{
- /**
- * @var IssueToNumberTransformerFactory
- */
- private $factory;
+ private $entityManager;
- public function __construct(IssueToNumberTransformerFactory $factory)
+ public function __construct(EntityManager $entityManager)
{
- $this->factory = $factory;
+ $this->entityManager = $entityManager;
}
public function buildForm(FormBuilderInterface $builder, array $options)
{
- $transformer = $this->factory->create($options['om']);
+ $builder
+ ->add('description', 'textarea')
+ ->add('issue', 'text', array(
+ // validation message if the data transformer fails
+ 'invalid_message' => 'That is not a valid issue number'
+ ));
- $builder->add(
- $builder->create('issue', 'text')
- ->addModelTransformer($transformer)
- );
- }
+ // ...
- public function setDefaultOptions(OptionsResolverInterface $resolver)
- {
- $resolver
- ->setDefaults(array(
- 'data_class' => 'AppBundle\Entity\Task',
- ))
- ->setRequired(array('om'))
- ;
+ $builder->get('issue')
+ ->addModelTransformer(new IssueToNumberTransformer($this->entityManager));
}
+
+ // ...
}
-This example requires that you pass in the entity manager as an option
-when creating your form. Later, you'll learn how you could create a custom
-``issue`` field type to avoid needing to do this in your controller::
+Now, when you create your ``TaskType``, you'll need to pass in the entity manager::
+
+ // e.g. in a controller somewhere
+ $entityManager = $this->getDoctrine()->getManager();
+ $form = $this->createForm(new TaskType($entityManager), $task);
- $taskForm = $this->createForm('app_task', $task, array(
- 'om' => 'default',
- ));
+ // ...
+
+.. note::
+
+ To make this step easier (especially if ``TaskType`` is embedded into other
+ form type classes), you might choose to :ref:`register your form type as a service `.
Cool, you're done! Your user will be able to enter an issue number into the
text field and it will be transformed back into an Issue object. This means
@@ -254,103 +302,47 @@ its error message can be controlled with the ``invalid_message`` field option.
.. caution::
- Notice that adding a transformer requires using a slightly more complicated
- syntax when adding the field. The following is **wrong**, as the transformer
- would be applied to the entire form, instead of just this field::
+ Be careful when adding your transformers. For example, the following is **wrong**,
+ as the transformer would be applied to the entire form, instead of just this
+ field::
// THIS IS WRONG - TRANSFORMER WILL BE APPLIED TO THE ENTIRE FORM
// see above example for correct code
$builder->add('issue', 'text')
->addModelTransformer($transformer);
-Model and View Transformers
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-In the above example, the transformer was used as a "model" transformer.
-In fact, there are two different types of transformers and three different
-types of underlying data.
-
-.. image:: /images/cookbook/form/DataTransformersTypes.png
- :align: center
-
-In any form, the three different types of data are:
-
-1) **Model data** - This is the data in the format used in your application
- (e.g. an ``Issue`` object). If you call ``Form::getData`` or ``Form::setData``,
- you're dealing with the "model" data.
-
-2) **Norm Data** - This is a normalized version of your data, and is commonly
- the same as your "model" data (though not in our example). It's not commonly
- used directly.
-
-3) **View Data** - This is the format that's used to fill in the form fields
- themselves. It's also the format in which the user will submit the data. When
- you call ``Form::submit($data)``, the ``$data`` is in the "view" data format.
-
-The two different types of transformers help convert to and from each of these
-types of data:
-
-**Model transformers**:
- - ``transform``: "model data" => "norm data"
- - ``reverseTransform``: "norm data" => "model data"
-
-**View transformers**:
- - ``transform``: "norm data" => "view data"
- - ``reverseTransform``: "view data" => "norm data"
-
-Which transformer you need depends on your situation.
-
-To use the view transformer, call ``addViewTransformer``.
-
-So why Use the Model Transformer?
----------------------------------
-
-In this example, the field is a ``text`` field, and a text field is always
-expected to be a simple, scalar format in the "norm" and "view" formats. For
-this reason, the most appropriate transformer was the "model" transformer
-(which converts to/from the *norm* format - string issue number - to the *model*
-format - Issue object).
+Creating a Reusable issue_selector Field
+----------------------------------------
-The difference between the transformers is subtle and you should always think
-about what the "norm" data for a field should really be. For example, the
-"norm" data for a ``text`` field is a string, but is a ``DateTime`` object
-for a ``date`` field.
-
-Using Transformers in a custom Field Type
------------------------------------------
-
-In the above example, you applied the transformer to a normal ``text`` field.
-This was easy, but has two downsides:
-
-1) You need to always remember to apply the transformer whenever you're adding
-a field for issue numbers.
-
-2) You need to worry about passing in the ``em`` option whenever you're creating
-a form that uses the transformer.
+In the above example, you applied the transformer to a normal ``text`` field. But
+if you do this transformation a lot, it might be better to
+:doc:`create a custom field type `.
+that does this automatically.
-Because of these, you may choose to :doc:`create a custom field type `.
First, create the custom field type class::
// src/AppBundle/Form/IssueSelectorType.php
+
namespace AppBundle\Form;
- use AppBundle\Form\DataTransformer\IssueToNumberTransformerFactory;
+ use AppBundle\Form\DataTransformer\IssueToNumberTransformer;
+ use Doctrine\ORM\EntityManager;
use Symfony\Component\Form\AbstractType;
use Symfony\Component\Form\FormBuilderInterface;
use Symfony\Component\OptionsResolver\OptionsResolverInterface;
class IssueSelectorType extends AbstractType
{
- private $factory;
-
- public function __construct(IssueToNumberTransformerFactory $factory)
+ private $entityManager;
+
+ public function __construct(EntityManager $entityManager)
{
- $this->factory = $factory;
+ $this->entityManager = $entityManager;
}
public function buildForm(FormBuilderInterface $builder, array $options)
{
- $transformer = $this->factory->create($options['om']);
+ $transformer = new IssueToNumberTransformer($this->entityManager);
$builder->addModelTransformer($transformer);
}
@@ -358,7 +350,6 @@ First, create the custom field type class::
{
$resolver->setDefaults(array(
'invalid_message' => 'The selected issue does not exist',
- 'om' => 'default'
));
}
@@ -373,6 +364,9 @@ First, create the custom field type class::
}
}
+Great! This will act and render like a text field (``getParent()``), but will automatically
+have the data transformer *and* a nice default value for the ``invalid_message`` option.
+
Next, register your type as a service and tag it with ``form.type`` so that
it's recognized as a custom field type:
@@ -380,27 +374,20 @@ it's recognized as a custom field type:
.. code-block:: yaml
+ # app/config/services.yml
services:
- app.issue_transformer_factory:
- class: AppBundle\Form\DataTransformer\IssueToNumberTransformerFactory
- arguments: ["@doctrine"]
- public: false
app.type.issue_selector:
class: AppBundle\Form\IssueSelectorType
- arguments: ["@app.issue_transformer_factory"]
+ arguments: ["@doctrine.orm.entity_manager"]
tags:
- { name: form.type, alias: issue_selector }
+
.. code-block:: xml
-
-
-
-
-
+
@@ -409,21 +396,12 @@ it's recognized as a custom field type:
use Symfony\Component\DependencyInjection\Definition;
use Symfony\Component\DependencyInjection\Reference;
// ...
-
- $container
- ->setDefinition('app.issue_transformer_factory', new Definition(
- 'AppBundle\Form\DataTransformer\IssueToNumberTransformerFactory'
- ), array(
- new Reference('doctrine'),
- ))
- ->setPublic(false)
- ;
-
+
$container
->setDefinition('app.type.issue_selector', new Definition(
'AppBundle\Form\IssueSelectorType'
), array(
- new Reference('app.issue_transformer_factory'),
+ new Reference('doctrine.orm.entity_manager'),
))
->addTag('form.type', array(
'alias' => 'issue_selector',
@@ -434,23 +412,73 @@ Now, whenever you need to use your special ``issue_selector`` field type,
it's quite easy::
// src/AppBundle/Form/TaskType.php
- namespace AppBundle\Form;
-
- use Symfony\Component\Form\AbstractType;
- use Symfony\Component\Form\FormBuilderInterface;
+ use AppBundle\Form\DataTransformer\IssueToNumberTransformer;
class TaskType extends AbstractType
{
public function buildForm(FormBuilderInterface $builder, array $options)
{
$builder
- ->add('task')
- ->add('dueDate', null, array('widget' => 'single_text'))
+ ->add('description', 'textarea')
->add('issue', 'issue_selector');
}
- public function getName()
- {
- return 'task';
- }
+ // ...
}
+
+About Model and View Transformers
+---------------------------------
+
+In the above example, the transformer was used as a "model" transformer.
+In fact, there are two different types of transformers and three different
+types of underlying data.
+
+.. image:: /images/cookbook/form/DataTransformersTypes.png
+ :align: center
+
+In any form, the three different types of data are:
+
+#. **Model data** - This is the data in the format used in your application
+ (e.g. an ``Issue`` object). If you call ``Form::getData()`` or ``Form::setData()``,
+ you're dealing with the "model" data.
+
+#. **Norm Data** - This is a normalized version of your data and is commonly
+ the same as your "model" data (though not in our example). It's not commonly
+ used directly.
+
+#. **View Data** - This is the format that's used to fill in the form fields
+ themselves. It's also the format in which the user will submit the data. When
+ you call ``Form::submit($data)``, the ``$data`` is in the "view" data format.
+
+The two different types of transformers help convert to and from each of these
+types of data:
+
+**Model transformers**:
+ - ``transform``: "model data" => "norm data"
+ - ``reverseTransform``: "norm data" => "model data"
+
+**View transformers**:
+ - ``transform``: "norm data" => "view data"
+ - ``reverseTransform``: "view data" => "norm data"
+
+Which transformer you need depends on your situation.
+
+To use the view transformer, call ``addViewTransformer``.
+
+So why Use the Model Transformer?
+---------------------------------
+
+In this example, the field is a ``text`` field, and a text field is always
+expected to be a simple, scalar format in the "norm" and "view" formats. For
+this reason, the most appropriate transformer was the "model" transformer
+(which converts to/from the *norm* format - string issue number - to the *model*
+format - Issue object).
+
+The difference between the transformers is subtle and you should always think
+about what the "norm" data for a field should really be. For example, the
+"norm" data for a ``text`` field is a string, but is a ``DateTime`` object
+for a ``date`` field.
+
+.. tip::
+
+ As a general rule, the normalized data should contain as much information as possible.