days

type: array default: 0 to 31

List of days available to the days field type. This option is only relevant when the widget option is set to choice:

1
2
3
4
5

// values displayed to users range from 0 to 30 (both inclusive)
'days' => range(1, 31),

// values displayed to users range from 1 to 31 (both inclusive)
'days' => array_combine(range(1, 31), range(1, 31)),

placeholder

type: string or array

If your widget option is set to choice, then this field will be represented as a series of select boxes. The placeholder option can be used to add a "blank" entry to the top of each select box:

1
2
3

$builder->add('remindEvery', DateIntervalType::class, [
    'placeholder' => '',
]);

Alternatively, you can specify a string to be displayed for the "blank" value:

1
2
3

$builder->add('remindEvery', DateIntervalType::class, [
    'placeholder' => ['years' => 'Years', 'months' => 'Months', 'days' => 'Days'],
]);

hours

type: array default: 0 to 24

List of hours available to the hours field type. This option is only relevant when the widget option is set to choice:

1
2
3
4
5

// values displayed to users range from 0 to 23 (both inclusive)
'hours' => range(1, 24),

// values displayed to users range from 1 to 24 (both inclusive)
'hours' => array_combine(range(1, 24), range(1, 24)),

input

type: string default: dateinterval

The format of the input data - i.e. the format that the interval is stored on your underlying object. Valid values are:

• string (a string formatted with ISO 8601 standard, e.g. P7Y6M5DT12H15M30S)
• dateinterval (a DateInterval object)
• array (e.g. ['days' => '1', 'hours' => '12',])

The value that comes back from the form will also be normalized back into this format.

labels

type: array default: (see below)

The labels displayed for each of the elements of this type. The default values are null, so they display the "humanized version" of the child names (Invert, Years, etc.):

1
2
3
4
5
6
7
8
9
10

'labels' => [
    'invert' => null,
    'years' => null,
    'months' => null,
    'weeks' => null,
    'days' => null,
    'hours' => null,
    'minutes' => null,
    'seconds' => null,
]

minutes

type: array default: 0 to 60

List of minutes available to the minutes field type. This option is only relevant when the widget option is set to choice:

1
2
3
4
5

// values displayed to users range from 0 to 59 (both inclusive)
'minutes' => range(1, 60),

// values displayed to users range from 1 to 60 (both inclusive)
'minutes' => array_combine(range(1, 60), range(1, 60)),

months

type: array default: 0 to 12

List of months available to the months field type. This option is only relevant when the widget option is set to choice:

1
2
3
4
5

// values displayed to users range from 0 to 11 (both inclusive)
'months' => range(1, 12),

// values displayed to users range from 1 to 12 (both inclusive)
'months' => array_combine(range(1, 12), range(1, 12)),

seconds

type: array default: 0 to 60

List of seconds available to the seconds field type. This option is only relevant when the widget option is set to choice:

1
2
3
4
5

// values displayed to users range from 0 to 59 (both inclusive)
'seconds' => range(1, 60),

// values displayed to users range from 1 to 60 (both inclusive)
'seconds' => array_combine(range(1, 60), range(1, 60)),

weeks

type: array default: 0 to 52

List of weeks available to the weeks field type. This option is only relevant when the widget option is set to choice:

1
2
3
4
5

// values displayed to users range from 0 to 51 (both inclusive)
'weeks' => range(1, 52),

// values displayed to users range from 1 to 52 (both inclusive)
'weeks' => array_combine(range(1, 52), range(1, 52)),

widget

type: string default: choice

The basic way in which this field should be rendered. Can be one of the following:

• choice: renders one to six select inputs for years, months, weeks, days, hours, minutes and/or seconds, depending on the with_years, with_months, with_weeks, with_days, with_hours, with_minutes and with_seconds options. Default: Three fields for years, months and days.
• text: renders one to six text inputs for years, months, weeks, days, hours, minutes and/or seconds, depending on the with_years, with_months, with_weeks, with_days, with_hours, with_minutes and with_seconds options. Default: Three fields for years, months and days.
• integer: renders one to six integer inputs for years, months, weeks, days, hours, minutes and/or seconds, depending on the with_years, with_months, with_weeks, with_days, with_hours, with_minutes and with_seconds options. Default: Three fields for years, months and days.
• single_text: renders a single input of type text. User's input will be validated against the form PnYnMnDTnHnMnS (or PnW if using only weeks).

with_days

type: Boolean default: true

Whether or not to include days in the input. This will result in an additional input to capture days.

with_hours

type: Boolean default: false

Whether or not to include hours in the input. This will result in an additional input to capture hours.

with_invert

type: Boolean default: false

Whether or not to include invert in the input. This will result in an additional checkbox. This can not be used when the widget option is set to single_text.

with_minutes

type: Boolean default: false

Whether or not to include minutes in the input. This will result in an additional input to capture minutes.

with_months

type: Boolean default: true

Whether or not to include months in the input. This will result in an additional input to capture months.

with_seconds

type: Boolean default: false

Whether or not to include seconds in the input. This will result in an additional input to capture seconds.

with_weeks

type: Boolean default: false

Whether or not to include weeks in the input. This will result in an additional input to capture weeks.

with_years

type: Boolean default: true

Whether or not to include years in the input. This will result in an additional input to capture years.

years

type: array default: 0 to 100

List of years available to the years field type. This option is only relevant when the widget option is set to choice:

1
2
3
4
5

// values displayed to users range from 0 to 99 (both inclusive)
'years' => range(1, 100),

// values displayed to users range from 1 to 100 (both inclusive)
'years' => array_combine(range(1, 100), range(1, 100)),

invalid_message

type: string default: This value is not valid

This is the validation error message that's used if the data entered into this field doesn't make sense (i.e. fails validation).

This might happen, for example, if the user enters a nonsense string into a TimeType field that cannot be converted into a real time or if the user enters a string (e.g. apple) into a number field.

Normal (business logic) validation (such as when setting a minimum length for a field) should be set using validation messages with your validation rules (reference).

attr

type: array default: []

If you want to add extra attributes to an HTML field representation you can use the attr option. It's an associative array with HTML attributes as keys. This can be useful when you need to set a custom class for some widget:

1
2
3

$builder->add('body', TextareaType::class, [
    'attr' => ['class' => 'tinymce'],
]);

data

type: mixed default: Defaults to field of the underlying structure.

When you create a form, each field initially displays the value of the corresponding property of the form's domain data (e.g. if you bind an object to the form). If you want to override this initial value for the form or an individual field, you can set it in the data option:

1
2
3
4
5
6

use Symfony\Component\Form\Extension\Core\Type\HiddenType;
// ...

$builder->add('token', HiddenType::class, [
    'data' => 'abcdef',
]);

disabled

type: boolean default: false

If you don't want a user to modify the value of a field, you can set the disabled option to true. Any submitted value will be ignored.

help

type: string or TranslatableMessage default: null

Allows you to define a help message for the form field, which by default is rendered below the field:

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

use Symfony\Component\Translation\TranslatableMessage;

$builder
    ->add('zipCode', null, [
        'help' => 'The ZIP/Postal code for your credit card\'s billing address.',
    ])

    // ...

    ->add('status', null, [
        'help' => new TranslatableMessage('order.status', ['%order_id%' => $order->getId()], 'store'),
    ])
;

help_attr

type: array default: []

Sets the HTML attributes for the element used to display the help message of the form field. Its value is an associative array with HTML attribute names as keys. These attributes can also be set in the template:

1
2
3

{{ form_help(form.name, 'Your name', {
    'help_attr': {'class': 'CUSTOM_LABEL_CLASS'}
}) }}

help_html

type: boolean default: false

By default, the contents of the help option are escaped before rendering them in the template. Set this option to true to not escape them, which is useful when the help contains HTML elements.

inherit_data

type: boolean default: false

This option determines if the form will inherit data from its parent form. This can be useful if you have a set of fields that are duplicated across multiple forms. See How to Reduce Code Duplication with "inherit_data".

invalid_message_parameters

type: array default: []

When setting the invalid_message option, you may need to include some variables in the string. This can be done by adding placeholders to that option and including the variables in this option:

1
2
3
4
5

$builder->add('someField', SomeFormType::class, [
    // ...
    'invalid_message' => 'You entered an invalid value, it should include %num% letters',
    'invalid_message_parameters' => ['%num%' => 6],
]);

mapped

type: boolean default: true

If you wish the field to be ignored when reading or writing to the object, you can set the mapped option to false.

row_attr

type: array default: []

An associative array of the HTML attributes added to the element which is used to render the form type row:

1
2
3

$builder->add('body', TextareaType::class, [
    'row_attr' => ['class' => 'text-editor', 'id' => '...'],
]);