Add dateinterval type reference

reference/forms/types.rst

@@ -29,6 +29,7 @@ Form Types Reference
    types/currency
 
    types/date
+   types/dateinterval
    types/datetime
    types/time
    types/birthday

reference/forms/types/dateinterval.rst

@@ -0,0 +1,290 @@
+.. index::
+   single: Forms; Fields; DateIntervalType
+
+DateIntervalType Field Type
+===========================
+
+This field type allows the user to modify data that represents a specific
+date interval. It can be rendered as a integer or text input or select tags.
+
+The underlying format of the data can be a ``DateInterval`` object,
+a `RFC 3339`_ duration string (e.g. ``P1DT12H``) or an array.
+
++----------------------+-----------------------------------------------------------------------------------+
+| Underlying Data Type | can be ``DateInterval``, string or array (see the ``input`` option)               |
++----------------------+-----------------------------------------------------------------------------------+
+| Rendered as          | single text box or up to six select, text or integer boxes plus optional checkbox |
++----------------------+-----------------------------------------------------------------------------------+
+| Options              | - `days`_                                                                         |
+|                      | - `placeholder`_                                                                  |
+|                      | - `hours`_                                                                        |
+|                      | - `input`_                                                                        |
+|                      | - `minutes`_                                                                      |
+|                      | - `months`_                                                                       |
+|                      | - `seconds`_                                                                      |
+|                      | - `weeks`_                                                                        |
+|                      | - `widget`_                                                                       |
+|                      | - `with_days`_                                                                    |
+|                      | - `with_hours`_                                                                   |
+|                      | - `with_invert`_                                                                  |
+|                      | - `with_minutes`_                                                                 |
+|                      | - `with_months`_                                                                  |
+|                      | - `with_seconds`_                                                                 |
+|                      | - `with_weeks`_                                                                   |
+|                      | - `with_years`_                                                                   |
+|                      | - `years`_                                                                        |
++----------------------+-----------------------------------------------------------------------------------+
+| Inherited            | - `data`_                                                                         |
+| options              | - `disabled`_                                                                     |
+|                      | - `inherit_data`_                                                                 |
+|                      | - `invalid_message`_                                                              |
+|                      | - `invalid_message_parameters`_                                                   |
+|                      | - `mapped`_                                                                       |
++----------------------+-----------------------------------------------------------------------------------+
+| Parent type          | :doc:`form </reference/forms/types/form>`                                         |
++----------------------+-----------------------------------------------------------------------------------+
+| Class                | :class:`Symfony\\Component\\Form\\Extension\\Core\\Type\\DateIntervalType`        |
++----------------------+-----------------------------------------------------------------------------------+
+
+Basic Usage
+-----------
+
+This field type is highly configurable, but easy to use. The most important
+options are ``input`` and ``widget``.
+
+Suppose that you have a ``remindEvery`` field whose underlying interval is a
+``DateInterval`` object. The following configures the ``dateinterval`` type
+for that field as **three different choice fields**:
+
+.. code-block:: php
+
+    $builder->add('remindEvery', DateIntervalType::class, array(
+        'widget' => 'choice',
+    ));
+
+The ``input`` option *must* be changed to match the type of the underlying
+interval data. For example, if the ``remindEvery`` field's data were a
+ISO 8601 duration string you'd need to set ``input`` to ``string``:
+
+.. code-block:: php
+
+    $builder->add('remindEvery', DateIntervalType::class, array(
+        'input'  => 'string',
+        'widget' => 'choice',
+    ));
+
+The field also supports an ``array`` as valid ``input`` option values.
+
+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 `RFC 3339`_ 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.
+
+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``
+
+Defines the ``widget`` option for the single interval component inputs.
+
+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
+input to capture seconds.
+
+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``::
+
+    'years' => range(1, 100)
+
+Inherited Options
+-----------------
+
+These options inherit from the :doc:`form </reference/forms/types/form>` type:
+
+.. include:: /reference/forms/types/options/data.rst.inc
+
+.. include:: /reference/forms/types/options/disabled.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
+
+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.
+============  ===========  ========================================
+
+.. _`RFC 3339`: http://tools.ietf.org/html/rfc3339

reference/forms/types/map.rst.inc

@@ -28,6 +28,7 @@ Date and Time Fields
 ~~~~~~~~~~~~~~~~~~~~
 
 * :doc:`DateType </reference/forms/types/date>`
+* :doc:`DateIntervalType </reference/forms/types/dateinterval>`
 * :doc:`DateTimeType </reference/forms/types/datetime>`
 * :doc:`TimeType </reference/forms/types/time>`
 * :doc:`BirthdayType </reference/forms/types/birthday>`