.. index:: single: Forms; Fields; TimeType TimeType Field ============== A field to capture time input. This can be rendered as a text field, a series of text fields (e.g. hour, minute, second) or a series of select fields. The underlying data can be stored as 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 | can be various tags (see below) | +----------------------+-----------------------------------------------------------------------------+ | Options | - `choice_translation_domain`_ | | | - `placeholder`_ | | | - `hours`_ | | | - `html5`_ | | | - `input`_ | | | - `input_format`_ | | | - `minutes`_ | | | - `model_timezone`_ | | | - `reference_date`_ | | | - `seconds`_ | | | - `view_timezone`_ | | | - `widget`_ | | | - `with_minutes`_ | | | - `with_seconds`_ | +----------------------+-----------------------------------------------------------------------------+ | Overridden options | - `by_reference`_ | | | - `compound`_ | | | - `data_class`_ | | | - `error_bubbling`_ | +----------------------+-----------------------------------------------------------------------------+ | Inherited | - `attr`_ | | options | - `data`_ | | | - `disabled`_ | | | - `error_mapping`_ | | | - `help`_ | | | - `help_attr`_ | | | - `help_html`_ | | | - `inherit_data`_ | | | - `invalid_message`_ | | | - `invalid_message_parameters`_ | | | - `mapped`_ | | | - `row_attr`_ | +----------------------+-----------------------------------------------------------------------------+ | Parent type | FormType | +----------------------+-----------------------------------------------------------------------------+ | Class | :class:`Symfony\\Component\\Form\\Extension\\Core\\Type\\TimeType` | +----------------------+-----------------------------------------------------------------------------+ .. include:: /reference/forms/types/options/_debug_form.rst.inc Basic Usage ----------- The most important options are ``input`` and ``widget``. Suppose that you have a ``startTime`` field whose underlying time data is a ``DateTime`` object. The following configures the ``TimeType`` for that field as two different choice fields:: use Symfony\Component\Form\Extension\Core\Type\TimeType; // ... $builder->add('startTime', TimeType::class, [ 'input' => 'datetime', 'widget' => 'choice', ]); The ``input`` option *must* be changed to match the type of the underlying date data. For example, if the ``startTime`` field's data were a unix timestamp, you'd need to set ``input`` to ``timestamp``:: use Symfony\Component\Form\Extension\Core\Type\TimeType; // ... $builder->add('startTime', TimeType::class, [ 'input' => 'timestamp', 'widget' => 'choice', ]); The field also supports an ``array`` and ``string`` as valid ``input`` option values. Field Options ------------- .. include:: /reference/forms/types/options/choice_translation_domain.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:: $builder->add('startTime', 'time', [ 'placeholder' => 'Select a value', ]); Alternatively, you can use an array that configures different placeholder values for the hour, minute and second fields:: $builder->add('startTime', 'time', [ 'placeholder' => [ 'hour' => 'Hour', 'minute' => 'Minute', 'second' => 'Second', ] ]); .. 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. ``12:17:26``) * ``datetime`` (a ``DateTime`` object) * ``datetime_immutable`` (a ``DateTimeImmutable`` object) * ``array`` (e.g. ``['hour' => 12, 'minute' => 17, 'second' => 26]``) * ``timestamp`` (e.g. ``1307232000``) The value that comes back from the form will also be normalized back into this format. input_format ~~~~~~~~~~~~ **type**: ``string`` **default**: ``H:i:s`` If the ``input`` option is set to ``string``, this option specifies the format of the time. This must be a valid `PHP time format`_. .. include:: /reference/forms/types/options/minutes.rst.inc .. include:: /reference/forms/types/options/model_timezone.rst.inc .. caution:: When using different values for ``model_timezone`` and `view_timezone`_, a `reference_date`_ must be configured. reference_date ~~~~~~~~~~~~~~ **type**: ``DateTimeInterface`` **default**: ``null`` Configuring a reference date is required when the `model_timezone`_ and `view_timezone`_ are different. Timezone conversions will be calculated based on this date. .. include:: /reference/forms/types/options/seconds.rst.inc .. include:: /reference/forms/types/options/view_timezone.rst.inc When no `reference_date`_ is set the ``view_timezone`` defaults to the configured `model_timezone`_. .. caution:: When using different values for `model_timezone`_ and ``view_timezone``, a `reference_date`_ must be configured. widget ~~~~~~ **type**: ``string`` **default**: ``choice`` The basic way in which this field should be rendered. Can be one of the following: * ``choice``: renders one, two (default) or three select inputs (hour, minute, second), depending on the `with_minutes`_ and `with_seconds`_ options. * ``text``: renders one, two (default) or three text inputs (hour, minute, second), depending on the `with_minutes`_ and `with_seconds`_ options. * ``single_text``: renders a single input of type ``time``. User's input will be validated against the form ``hh:mm`` (or ``hh:mm:ss`` if using seconds). .. caution:: Combining the widget type ``single_text`` and the `with_minutes`_ option set to ``false`` can cause unexpected behavior in the client as the input type ``time`` might not support selecting an hour only. .. include:: /reference/forms/types/options/with_minutes.rst.inc .. include:: /reference/forms/types/options/with_seconds.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/error_mapping.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 Form Variables -------------- +--------------+-------------+----------------------------------------------------------------------+ | Variable | Type | Usage | +==============+=============+======================================================================+ | widget | ``mixed`` | The value of the `widget`_ option. | +--------------+-------------+----------------------------------------------------------------------+ | with_minutes | ``boolean`` | The value of the `with_minutes`_ option. | +--------------+-------------+----------------------------------------------------------------------+ | with_seconds | ``boolean`` | The value of the `with_seconds`_ option. | +--------------+-------------+----------------------------------------------------------------------+ | type | ``string`` | Only present when widget is ``single_text`` and HTML5 is activated, | | | | contains the input type to use (``datetime``, ``date`` or ``time``). | +--------------+-------------+----------------------------------------------------------------------+ .. _`PHP time format`: https://secure.php.net/manual/en/function.date.php