.. index:: single: Forms; Fields; DateTimeType DateTimeType Field ================== This field type allows the user to modify data that represents a specific date and time (e.g. ``1984-06-05 12:15:30``). Can be rendered as a text input or select tags. The underlying format of the data can be a ``DateTime`` object, a string, a timestamp or an array. +----------------------+-----------------------------------------------------------------------------+ | Underlying Data Type | can be ``DateTime``, string, timestamp, or array (see the ``input`` option) | +----------------------+-----------------------------------------------------------------------------+ | Rendered as | single text box or three select fields | +----------------------+-----------------------------------------------------------------------------+ | Options | - `choice_translation_domain`_ | | | - `date_format`_ | | | - `date_label`_ | | | - `date_widget`_ | | | - `days`_ | | | - `placeholder`_ | | | - `format`_ | | | - `hours`_ | | | - `html5`_ | | | - `input`_ | | | - `input_format`_ | | | - `minutes`_ | | | - `model_timezone`_ | | | - `months`_ | | | - `seconds`_ | | | - `time_label`_ | | | - `time_widget`_ | | | - `view_timezone`_ | | | - `widget`_ | | | - `with_minutes`_ | | | - `with_seconds`_ | | | - `years`_ | +----------------------+-----------------------------------------------------------------------------+ | Overridden options | - `by_reference`_ | | | - `compound`_ | | | - `data_class`_ | | | - `error_bubbling`_ | +----------------------+-----------------------------------------------------------------------------+ | Inherited | - `attr`_ | | options | - `data`_ | | | - `disabled`_ | | | - `help`_ | | | - `help_attr`_ | | | - `help_html`_ | | | - `inherit_data`_ | | | - `invalid_message`_ | | | - `invalid_message_parameters`_ | | | - `mapped`_ | | | - `row_attr`_ | +----------------------+-----------------------------------------------------------------------------+ | Parent type | :doc:`FormType ` | +----------------------+-----------------------------------------------------------------------------+ | Class | :class:`Symfony\\Component\\Form\\Extension\\Core\\Type\\DateTimeType` | +----------------------+-----------------------------------------------------------------------------+ .. include:: /reference/forms/types/options/_debug_form.rst.inc Field Options ------------- .. include:: /reference/forms/types/options/choice_translation_domain.rst.inc date_format ~~~~~~~~~~~ **type**: ``integer`` or ``string`` **default**: ``IntlDateFormatter::MEDIUM`` Defines the ``format`` option that will be passed down to the date field. See the :ref:`DateType's format option ` for more details. date_label ~~~~~~~~~~ **type**: ``string`` | ``null`` **default**: The label is "guessed" from the field name Sets the label that will be used when rendering the date widget. Setting it to ``false`` will suppress the label:: use Symfony\Component\Form\Extension\Core\Type\DateTimeType; $builder->add('startDateTime', DateTimeType::class, [ 'date_label' => 'Starts On', ]); date_widget ~~~~~~~~~~~ .. include:: /reference/forms/types/options/date_widget_description.rst.inc .. include:: /reference/forms/types/options/days.rst.inc placeholder ~~~~~~~~~~~ **type**: ``string`` | ``array`` If your widget option is set to ``choice``, then this field will be represented as a series of ``select`` boxes. When the placeholder value is a string, it will be used as the **blank value** of all select boxes:: use Symfony\Component\Form\Extension\Core\Type\DateTimeType; $builder->add('startDateTime', DateTimeType::class, [ 'placeholder' => 'Select a value', ]); Alternatively, you can use an array that configures different placeholder values for the year, month, day, hour, minute and second fields:: use Symfony\Component\Form\Extension\Core\Type\DateTimeType; $builder->add('startDateTime', DateTimeType::class, [ 'placeholder' => [ 'year' => 'Year', 'month' => 'Month', 'day' => 'Day', 'hour' => 'Hour', 'minute' => 'Minute', 'second' => 'Second', ] ]); format ~~~~~~ **type**: ``string`` **default**: ``Symfony\Component\Form\Extension\Core\Type\DateTimeType::HTML5_FORMAT`` If the ``widget`` option is set to ``single_text``, this option specifies the format of the input, i.e. how Symfony will interpret the given input as a datetime string. It defaults to the `datetime local`_ format which is used by the HTML5 ``datetime-local`` field. Keeping the default value will cause the field to be rendered as an ``input`` field with ``type="datetime-local"``. For more information on valid formats, see `Date/Time Format Syntax`_. .. include:: /reference/forms/types/options/hours.rst.inc .. include:: /reference/forms/types/options/html5.rst.inc input ~~~~~ **type**: ``string`` **default**: ``datetime`` The format of the *input* data - i.e. the format that the date is stored on your underlying object. Valid values are: * ``string`` (e.g. ``2011-06-05 12:15:00``) * ``datetime`` (a ``DateTime`` object) * ``datetime_immutable`` (a ``DateTimeImmutable`` object) * ``array`` (e.g. ``[2011, 06, 05, 12, 15, 0]``) * ``timestamp`` (e.g. ``1307276100``) The value that comes back from the form will also be normalized back into this format. .. include:: /reference/forms/types/options/_date_limitation.rst.inc input_format ~~~~~~~~~~~~ **type**: ``string`` **default**: ``Y-m-d H:i:s`` .. include:: /reference/forms/types/options/date_input_format_description.rst.inc .. include:: /reference/forms/types/options/minutes.rst.inc .. include:: /reference/forms/types/options/model_timezone.rst.inc .. include:: /reference/forms/types/options/months.rst.inc .. include:: /reference/forms/types/options/seconds.rst.inc time_label ~~~~~~~~~~ **type**: ``string`` | ``null`` **default**: The label is "guessed" from the field name Sets the label that will be used when rendering the time widget. Setting it to ``false`` will suppress the label:: use Symfony\Component\Form\Extension\Core\Type\DateTimeType; $builder->add('startDateTime', DateTimeType::class, [ 'time_label' => 'Starts On', ]); time_widget ~~~~~~~~~~~ **type**: ``string`` **default**: ``choice`` Defines the ``widget`` option for the :doc:`TimeType `. .. include:: /reference/forms/types/options/view_timezone.rst.inc widget ~~~~~~ **type**: ``string`` **default**: ``null`` Defines the ``widget`` option for both the :doc:`DateType ` and :doc:`TimeType `. This can be overridden with the `date_widget`_ and `time_widget`_ options. .. include:: /reference/forms/types/options/with_minutes.rst.inc .. include:: /reference/forms/types/options/with_seconds.rst.inc .. include:: /reference/forms/types/options/years.rst.inc Overridden Options ------------------ by_reference ~~~~~~~~~~~~ **default**: ``false`` The ``DateTime`` classes are treated as immutable objects. .. include:: /reference/forms/types/options/compound_type.rst.inc .. include:: /reference/forms/types/options/data_class_date.rst.inc error_bubbling ~~~~~~~~~~~~~~ **default**: ``false`` Inherited Options ----------------- These options inherit from the :doc:`FormType `: .. include:: /reference/forms/types/options/attr.rst.inc .. include:: /reference/forms/types/options/data.rst.inc .. include:: /reference/forms/types/options/disabled.rst.inc .. include:: /reference/forms/types/options/help.rst.inc .. include:: /reference/forms/types/options/help_attr.rst.inc .. include:: /reference/forms/types/options/help_html.rst.inc .. include:: /reference/forms/types/options/inherit_data.rst.inc .. include:: /reference/forms/types/options/invalid_message.rst.inc .. include:: /reference/forms/types/options/invalid_message_parameters.rst.inc .. include:: /reference/forms/types/options/mapped.rst.inc .. include:: /reference/forms/types/options/row_attr.rst.inc Field Variables --------------- +----------+------------+----------------------------------------------------------------------+ | Variable | Type | Usage | +==========+============+======================================================================+ | widget | ``mixed`` | The value of the `widget`_ option. | +----------+------------+----------------------------------------------------------------------+ | type | ``string`` | Only present when widget is ``single_text`` and HTML5 is activated, | | | | contains the input type to use (``datetime``, ``date`` or ``time``). | +----------+------------+----------------------------------------------------------------------+ .. _`datetime local`: http://w3c.github.io/html-reference/datatypes.html#form.data.datetime-local .. _`Date/Time Format Syntax`: http://userguide.icu-project.org/formatparse/datetime#TOC-Date-Time-Format-Syntax