Defining the Field Type

In order to create the custom field type, first you have to create the class representing the field. In this situation the class holding the field type will be called GenderType and the file will be stored in the default location for form fields, which is <BundleName>\Form\Type. Make sure the field extends AbstractType:

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

// src/AppBundle/Form/Type/GenderType.php
namespace AppBundle\Form\Type;

use Symfony\Component\Form\AbstractType;
use Symfony\Component\OptionsResolver\OptionsResolver;
use Symfony\Component\Form\Extension\Core\Type\ChoiceType;

class GenderType extends AbstractType
{
    public function configureOptions(OptionsResolver $resolver)
    {
        $resolver->setDefaults(array(
            'choices' => array(
                'm' => 'Male',
                'f' => 'Female',
            )
        ));
    }

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

Here, the return value of the getParent function indicates that you're extending the ChoiceType field. This means that, by default, you inherit all of the logic and rendering of that field type. To see some of the logic, check out the ChoiceType class. There are three methods that are particularly important:

buildForm()

Each field type has a buildForm method, which is where you configure and build any field(s). Notice that this is the same method you use to setup your forms, and it works the same here.

buildView()

This method is used to set any extra variables you'll need when rendering your field in a template. For example, in ChoiceType, a multiple variable is set and used in the template to set (or not set) the multiple attribute on the select field. See Creating a Template for the Field for more details.

configureOptions()

This defines options for your form type that can be used in buildForm() and buildView(). There are a lot of options common to all fields (see FormType Field), but you can create any others that you need here.

The goal of this field was to extend the choice type to enable selection of a gender. This is achieved by fixing the choices to a list of possible genders.

Creating a Template for the Field

Each field type is rendered by a template fragment, which is determined in part by the class name of your type. For more information, see How to Customize Form Rendering.

In this case, since the parent field is ChoiceType, you don't need to do any work as the custom field type will automatically be rendered like a ChoiceType. But for the sake of this example, suppose that when your field is "expanded" (i.e. radio buttons or checkboxes, instead of a select field), you want to always render it in a ul element. In your form theme template (see above link for details), create a gender_widget block to handle this:

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

{# app/Resources/views/form/fields.html.twig #}
{% block gender_widget %}
    {% spaceless %}
        {% if expanded %}
            <ul {{ block('widget_container_attributes') }}>
            {% for child in form %}
                <li>
                    {{ form_widget(child) }}
                    {{ form_label(child) }}
                </li>
            {% endfor %}
            </ul>
        {% else %}
            {# just let the choice widget render the select tag #}
            {{ block('choice_widget') }}
        {% endif %}
    {% endspaceless %}
{% endblock %}

1
2
3
4
5
6
7
8
9
10
11
12
13
14

<!-- app/Resources/views/form/gender_widget.html.php -->
<?php if ($expanded) : ?>
    <ul <?php $view['form']->block($form, 'widget_container_attributes') ?>>
    <?php foreach ($form as $child) : ?>
        <li>
            <?php echo $view['form']->widget($child) ?>
            <?php echo $view['form']->label($child) ?>
        </li>
    <?php endforeach ?>
    </ul>
<?php else : ?>
    <!-- just let the choice widget render the select tag -->
    <?php echo $view['form']->renderBlock('choice_widget') ?>
<?php endif ?>

1
2
3
4

# app/config/config.yml
twig:
    form_themes:
        - 'form/fields.html.twig'

1
2
3
4

<!-- app/config/config.xml -->
<twig:config>
    <twig:form-theme>form/fields.html.twig</twig:form-theme>
</twig:config>

1
2
3
4
5
6

// app/config/config.php
$container->loadFromExtension('twig', array(
    'form_themes' => array(
        'form/fields.html.twig',
    ),
));

1
2
3
4
5
6

# app/config/config.yml
framework:
    templating:
        form:
            resources:
                - ':form:fields.html.php'

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

<!-- app/config/config.xml -->
<?xml version="1.0" encoding="UTF-8" ?>
<container xmlns="http://symfony.com/schema/dic/services"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:framework="http://symfony.com/schema/dic/symfony"
    xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd
    http://symfony.com/schema/dic/symfony http://symfony.com/schema/dic/symfony/symfony-1.0.xsd">

    <framework:config>
        <framework:templating>
            <framework:form>
                <framework:resource>:form:fields.html.php</twig:resource>
            </framework:form>
        </framework:templating>
    </framework:config>
</container>

1
2
3
4
5
6
7
8
9
10

// app/config/config.php
$container->loadFromExtension('framework', array(
    'templating' => array(
        'form' => array(
            'resources' => array(
                ':form:fields.html.php',
            ),
        ),
    ),
));

Using the Field Type

You can now use your custom field type immediately, simply by creating a new instance of the type in one of your forms:

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

// src/AppBundle/Form/Type/AuthorType.php
namespace AppBundle\Form\Type;

use Symfony\Component\Form\AbstractType;
use Symfony\Component\Form\FormBuilderInterface;
use AppBundle\Form\Type\GenderType;

class AuthorType extends AbstractType
{
    public function buildForm(FormBuilderInterface $builder, array $options)
    {
        $builder->add('gender_code', GenderType::class, array(
            'placeholder' => 'Choose a gender',
        ));
    }
}

But this only works because the GenderType is very simple. What if the gender codes were stored in configuration or in a database? The next section explains how more complex field types solve this problem.

Creating your Field Type as a Service

So far, this entry has assumed that you have a very simple custom field type. But if you need access to configuration, a database connection, or some other service, then you'll want to register your custom type as a service. For example, suppose that you're storing the gender parameters in configuration:

1
2
3
4
5

# app/config/config.yml
parameters:
    genders:
        m: Male
        f: Female

1
2
3
4
5
6
7

<!-- app/config/config.xml -->
<parameters>
    <parameter key="genders" type="collection">
        <parameter key="m">Male</parameter>
        <parameter key="f">Female</parameter>
    </parameter>
</parameters>

1
2
3

// app/config/config.php
$container->setParameter('genders.m', 'Male');
$container->setParameter('genders.f', 'Female');

To use the parameter, define your custom field type as a service, injecting the genders parameter value as the first argument to its to-be-created __construct function:

1
2
3
4
5
6
7
8

# src/AppBundle/Resources/config/services.yml
services:
    app.form.type.gender:
        class: AppBundle\Form\Type\GenderType
        arguments:
            - '%genders%'
        tags:
            - { name: form.type }

1
2
3
4
5

<!-- src/AppBundle/Resources/config/services.xml -->
<service id="app.form.type.gender" class="AppBundle\Form\Type\GenderType">
    <argument>%genders%</argument>
    <tag name="form.type" />
</service>

1
2
3
4
5
6
7
8
9
10

// src/AppBundle/Resources/config/services.php
use Symfony\Component\DependencyInjection\Definition;

$container
    ->setDefinition('app.form.type.gender', new Definition(
        'AppBundle\Form\Type\GenderType',
        array('%genders%')
    ))
    ->addTag('form.type')
;

First, add a __construct method to GenderType, which receives the gender configuration:

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

// src/AppBundle/Form/Type/GenderType.php
namespace AppBundle\Form\Type;

use Symfony\Component\OptionsResolver\OptionsResolver;

// ...

// ...
class GenderType extends AbstractType
{
    private $genderChoices;

    public function __construct(array $genderChoices)
    {
        $this->genderChoices = $genderChoices;
    }

    public function configureOptions(OptionsResolver $resolver)
    {
        $resolver->setDefaults(array(
            'choices' => $this->genderChoices,
        ));
    }

    // ...
}

Great! The GenderType is now fueled by the configuration parameters and registered as a service. Because you used the form.type alias in its configuration, your service will be used instead of creating a new GenderType. In other words, your controller does not need to change, it still looks like this:

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

// src/AppBundle/Form/Type/AuthorType.php
namespace AppBundle\Form\Type;

use Symfony\Component\Form\AbstractType;
use Symfony\Component\Form\FormBuilderInterface;
use AppBundle\Form\Type\GenderType;

class AuthorType extends AbstractType
{
    public function buildForm(FormBuilderInterface $builder, array $options)
    {
        $builder->add('gender_code', GenderType::class, array(
            'placeholder' => 'Choose a gender',
        ));
    }
}

Have fun!