DateIntervalType Field

DateIntervalType Field

New in version 3.2: The DateIntervalType field type was introduced in Symfony 3.2.

This field allows the user to select an interval of time. For example, if you want to allow the user to choose how often they receive a status email, they could use this field to choose intervals like every "10 minutes" or "3 days".

The field can be rendered in a variety of different ways (see widget) and can be configured to give you a DateInterval object, an ISO 8601 duration string (e.g. P1DT12H) or an array (see input).

Underlying Data Type can be DateInterval, string or array (see the input option)
Rendered as single text box, multiple text boxes or select fields - see the widget option
Options
Inherited options
Parent type FormType
Class DateIntervalType

Basic Usage

This field type is highly configurable, but easy to use. The most important options are input and widget.

You can configure a lot of different options, including exactly which range options to show (e.g. don't show "months", but do show "days"):

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
$builder->add('remindEvery', DateIntervalType::class, array(
    'widget'      => 'integer', // render a text field for each part
    // 'input'    => 'string',  // if you want the field to return a ISO 8601 string back to you

    // customize which text boxes are shown
    'with_years'  => false,
    'with_months' => false,
    'with_days'   => true,
    'with_hours'  => true,
));

Field Options

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:

'days' => 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:

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

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

$builder->add('remindEvery', DateIntervalType::class, array(
    'placeholder' => array('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:

'hours' => 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. array('days' => '1', 'hours' => '12',))

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

labels

New in version 3.3: The labels option was introduced in Symfony 3.3.

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
'labels' => array(
    'invert' => null,
    'years' => null,
    'months' => 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:

'minutes' => 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:

'months' => 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:

'seconds' => 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:

'weeks' => range(1, 52)

widget

type: string default: choice

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

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.

Caution

This can not be used when with_weeks is enabled.

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.

Caution

This can not be used when with_days is enabled.

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:

'years' => range(1, 100)

Inherited Options

These options inherit from the form type:

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, array(
    'data' => 'abcdef',
));

Caution

The data option always overrides the value taken from the domain data (object) when rendering. This means the object value is also overriden when the form edits an already persisted object, causing it to lose its persisted value when the form is submitted.

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.

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".

Caution

When a field has the inherit_data option set, it uses the data of the parent form as is. This means that Data Transformers won't be applied to that field.

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).

invalid_message_parameters

type: array default: array()

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('some_field', SomeFormType::class, array(
    // ...
    'invalid_message' => 'You entered an invalid value, it should include %num% letters',
    'invalid_message_parameters' => array('%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.

Field Variables

Variable Type Usage
widget mixed The value of the widget option.
with_days Boolean The value of the with_days option.
with_invert Boolean The value of the with_invert option.
with_hours Boolean The value of the with_hours option.
with_minutes Boolean The value of the with_minutes option.
with_months Boolean The value of the with_months option.
with_seconds Boolean The value of the with_seconds option.
with_weeks Boolean The value of the with_weeks option.
with_years Boolean The value of the with_years option.

This work, including the code samples, is licensed under a Creative Commons BY-SA 3.0 license.