Merge branch '3.0' into 3.1

* 3.0:
  Updated according to comments
  Improved nginx config to not expose other php files
  Removing all instances of choices_as_values in 3.0
  [Form] fixed EntityType choice options
  Adding information about using the date type as usable date picker field

Author: weaverryan

cookbook/configuration/web_server_configuration.rst

@@ -305,6 +305,12 @@ The **minimum configuration** to get your application running under Nginx is:
             # Remove the internal directive to allow URIs like this
             internal;
         }
+        
+        # return 404 for all other php files not matching the front controller
+        # this prevents access to other php files you don't want to be accessible.
+        location ~ \.php$ {
+          return 404;
+        }
 
         error_log /var/log/nginx/project_error.log;
         access_log /var/log/nginx/project_access.log;
@@ -318,14 +324,17 @@ The **minimum configuration** to get your application running under Nginx is:
 .. tip::
 
     This executes **only** ``app.php``, ``app_dev.php`` and ``config.php`` in
-    the web directory. All other files will be served as text. You **must**
-    also make sure that if you *do* deploy ``app_dev.php`` or ``config.php``
-    that these files are secured and not available to any outside user (the
-    IP address checking code at the top of each file does this by default).
+    the web directory. All other files ending in ".php" will be denied.
 
     If you have other PHP files in your web directory that need to be executed,
     be sure to include them in the ``location`` block above.
 
+.. caution::
+
+    After you deploy to production, make sure that you **cannot** access the ``app_dev.php``
+    or ``config.php`` scripts (i.e. ``http://example.com/app_dev.php`` and ``http://example.com/config.php``).
+    If you *can* access these, be sure to remove the ``DEV`` section from the above configuration.
+
 For advanced Nginx configuration options, read the official `Nginx documentation`_.
 
 .. _`Apache documentation`: http://httpd.apache.org/docs/

reference/forms/types/choice.rst

@@ -19,7 +19,7 @@ To use this field, you must specify *either* ``choices`` or ``choice_loader`` op
 |             | - `choice_name`_                                                             |
 |             | - `choice_translation_domain`_                                               |
 |             | - `choice_value`_                                                            |
-|             | - `choices_as_values`_                                                       |
+|             | - `choices_as_values`_ (deprecated)                                          |
 |             | - `expanded`_                                                                |
 |             | - `group_by`_                                                                |
 |             | - `multiple`_                                                                |
@@ -167,8 +167,6 @@ is the item's label and the array value is the item's value::
 
     $builder->add('inStock', ChoiceType::class, array(
         'choices' => array('In Stock' => true, 'Out of Stock' => false),
-        // always include this
-        'choices_as_values' => true,
     ));
 
 .. include:: /reference/forms/types/options/choice_attr.rst.inc
@@ -195,39 +193,8 @@ would replace the ``choices`` option.
 choices_as_values
 ~~~~~~~~~~~~~~~~~
 
-**type**: ``boolean`` **default**: false
-
-The ``choices_as_values`` option was added to keep backward compatibility with the
-*old* way of handling the ``choices`` option. When set to ``false`` (or omitted),
-the choice keys are used as the underlying value and the choice values are shown
-to the user.
-
-* Before 2.7 (and deprecated now)::
-
-    $builder->add('gender', 'choice', array(
-        // Shows "Male" to the user, returns "m" when selected
-        'choices'  => array('m' => 'Male', 'f' => 'Female'),
-        // before 2.7, this option didn't actually exist, but the
-        // behavior was equivalent to setting this to false in 2.7.
-        'choices_as_values' => false,
-    ));
-
-* Since 2.7::
-
-    $builder->add('gender', ChoiceType::class, array(
-        // Shows "Male" to the user, returns "m" when selected
-        'choices' => array('Male' => 'm', 'Female' => 'f'),
-        'choices_as_values' => true,
-    ));
-
-In Symfony 3.0, the ``choices_as_values`` option doesn't exist, but the ``choice``
-type behaves as if it were set to true:
-
-* Default for 3.0::
-
-    $builder->add('gender', ChoiceType::class, array(
-        'choices' => array('Male' => 'm', 'Female' => 'f'),
-    ));
+This option is deprecated and you should remove it from your 3.x projects (removing
+it will have *no* effect). For its purpose in 2.x, see the 2.7 documentation.
 
 .. include:: /reference/forms/types/options/expanded.rst.inc
 

reference/forms/types/date.rst

@@ -7,12 +7,8 @@ DateType Field
 A field that allows the user to modify date information via a variety of
 different HTML elements.
 
-The underlying data used for this field type can be a ``DateTime`` object,
-a string, a timestamp or an array. As long as the `input`_ option is set
-correctly, the field will take care of all of the details.
-
-The field can be rendered as a single text box, three text boxes (month,
-day and year) or three select boxes (see the `widget`_ option).
+This field can be rendered in a variety of different ways via the `widget`_ option
+and can understand a number of different input formats via the `input`_ option.
 
 +----------------------+-----------------------------------------------------------------------------+
 | Underlying Data Type | can be ``DateTime``, string, timestamp, or array (see the ``input`` option) |
@@ -56,31 +52,78 @@ This field type is highly configurable, but easy to use. The most important
 options are ``input`` and ``widget``.
 
 Suppose that you have a ``publishedAt`` field whose underlying date is a
-``DateTime`` object. The following configures the ``DateType`` type for that
-field as three different choice fields::
+``DateTime`` object. The following configures the ``date`` type for that
+field as **three different choice fields**::
 
     use Symfony\Component\Form\Extension\Core\Type\DateType;
     // ...
 
     $builder->add('publishedAt', DateType::class, array(
-        'input'  => 'datetime',
         'widget' => 'choice',
     ));
 
-The ``input`` option *must* be changed to match the type of the underlying
-date data. For example, if the ``publishedAt`` field's data were a unix
-timestamp, you'd need to set ``input`` to ``timestamp``::
+If your underlying date is *not* a ``DateTime`` object (e.g. it's a unix timestamp),
+configure the `input`_ option.
+
+Rendering a single HTML5 Textbox
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+For a better user experience, you may want to render a single text field and use
+some kind of "date picker" to help your user fill in the right format. To do that,
+use the ``single_text`` widget::
 
     use Symfony\Component\Form\Extension\Core\Type\DateType;
     // ...
 
     $builder->add('publishedAt', DateType::class, array(
-        'input'  => 'timestamp',
-        'widget' => 'choice',
+        // render as a single text box
+        'widget' => 'single_text',
+    ));
+
+This will render as an ``input type="date"`` HTML5 field, which means that **some -
+but not all - browsers will add nice date picker functionality to the field**. If you
+want to be absolutely sure that *every* user has a consistent date picker, use an
+external JavaScript library.
+
+For example, suppose you want to use the `Bootstrap Datepicker`_ library. First,
+make the following changes::
+
+    use Symfony\Component\Form\Extension\Core\Type\DateType;
+    // ...
+
+    $builder->add('publishedAt', DateType::class, array(
+        'widget' => 'single_text',
+
+        // do not render as type="date", to avoid HTML5 date pickers
+        'html5' => false,
+
+        // add a class that can eb selected in JavaScript
+        'attr' => ['class' => 'js-datepicker'],
     ));
 
-The field also supports an ``array`` and ``string`` as valid ``input`` option
-values.
+Assuming you're using jQuery, you can initialize the date picker via:
+
+.. code-block:: html
+
+    <script>
+        $(document).ready(function() {
+            $('.js-datepicker').datepicker({
+                format: 'yyyy-mm-dd'
+            });
+        });
+    </script>
+
+This ``format`` key tells the date picker to use the date format that Symfony expects.
+This can be tricky: if the date picker is misconfigured, Symfony won't understand
+the format and will throw a validation error. You can also configure the format
+that Symfony should expect via the `format`_ option.
+
+.. caution::
+
+    The string used by a JavaScript date picker to describe its format (e.g. ``yyyy-mm-dd``)
+    may not match the string that Symfony uses (e.g. ``yyyy-MM-dd``). This is because
+    different libraries use different formatting rules to describe the date format.
+    Be aware of this - it can be tricky to make the formats truly match!
 
 Field Options
 -------------
@@ -182,3 +225,5 @@ Field Variables
 +--------------+------------+----------------------------------------------------------------------+
 | date_pattern | ``string`` | A string with the date format to use.                                |
 +--------------+------------+----------------------------------------------------------------------+
+
+.. _`Bootstrap Datepicker`: https://github.com/eternicode/bootstrap-datepicker

reference/forms/types/entity.rst

@@ -17,15 +17,15 @@ objects from the database.
 |             | - `em`_                                                          |
 |             | - `query_builder`_                                               |
 +-------------+------------------------------------------------------------------+
-| Overridden  | - `choices`_                                                     |
-| options     | - `data_class`_                                                  |
+| Overridden  | - `choice_name`_                                                 |
+| options     | - `choice_value`_                                                |
+|             | - `choices`_                                                     |
+|             | - `data_class`_                                                  |
 +-------------+------------------------------------------------------------------+
 | Inherited   | from the :doc:`ChoiceType </reference/forms/types/choice>`:      |
 | options     |                                                                  |
 |             | - `choice_attr`_                                                 |
-|             | - `choice_name`_                                                 |
 |             | - `choice_translation_domain`_                                   |
-|             | - `choice_value`_                                                |
 |             | - `expanded`_                                                    |
 |             | - `group_by`_                                                    |
 |             | - `multiple`_                                                    |
@@ -126,7 +126,7 @@ Field Options
 choice_label
 ~~~~~~~~~~~~
 
-**type**: ``string`` or ``callable``
+**type**: ``string``, ``callable`` or :class:`Symfony\\Component\\PropertyAccess\\PropertyPath`
 
 This is the property that should be used for displaying the entities as text in
 the HTML element::
@@ -208,6 +208,40 @@ the Closure.
 Overridden Options
 ------------------
 
+choice_name
+~~~~~~~~~~~
+
+.. versionadded:: 2.7
+    The ``choice_name`` option was introduced in Symfony 2.7.
+
+**type**: ``string``, ``callable`` or :class:`Symfony\\Component\\PropertyAccess\\PropertyPath` **default**: id
+
+By default the name of each field is the id of the entity, if it can be read
+from the class metadata by an internal id reader. Otherwise the process will
+fall back to using increasing integers.
+
+choice_value
+~~~~~~~~~~~~
+
+.. versionadded:: 2.7
+    The ``choice_value`` option was introduced in Symfony 2.7.
+
+**type**: ``string``, ``callable`` or :class:`Symfony\\Component\\PropertyAccess\\PropertyPath` **default**: id
+
+As for the ``choice_name`` option, ``choice_value`` uses the id by default.
+It allows an optimization in the :class:``Symfony\\Bridge\\Doctrine\\Form\\ChoiceList\\Loader\\DoctrineChoiceLoader`` which will
+only load the ids passed as values while the form submission.
+It prevents all non submitted entities to be loaded from the database, even
+when defining the ``query_builder`` option.
+If it may be useful to set this option using an entity's property as string
+value (e.g for some API), you will gain performances by letting this option set
+by default.
+
+.. note::
+
+    If the id cannot be read, for BC, the component checks if the class implements
+    ``__toString()`` and will use an incremental integer otherwise.
+
 choices
 ~~~~~~~
 
@@ -232,12 +266,8 @@ These options inherit from the :doc:`ChoiceType </reference/forms/types/choice>`
 
 .. include:: /reference/forms/types/options/choice_attr.rst.inc
 
-.. include:: /reference/forms/types/options/choice_name.rst.inc
-
 .. include:: /reference/forms/types/options/choice_translation_domain.rst.inc
 
-.. include:: /reference/forms/types/options/choice_value.rst.inc
-
 .. include:: /reference/forms/types/options/expanded.rst.inc
 
 .. include:: /reference/forms/types/options/group_by.rst.inc

reference/forms/types/options/choice_attr.rst.inc

@@ -18,7 +18,6 @@ If an array, the keys of the ``choices`` array must be used as keys::
             'No' => false,
             'Maybe' => null,
         ),
-        'choices_as_values' => true,
         'choice_attr' => function($val, $key, $index) {
             // adds a class like attending_yes, attending_no, etc
             return ['class' => 'attending_'.strtolower($key)];

reference/forms/types/options/choice_label.rst.inc

@@ -16,7 +16,6 @@ more control::
             'no' => false,
             'maybe' => null,
         ),
-        'choices_as_values' => true,
         'choice_label' => function ($value, $key, $index) {
             if ($value == true) {
                 return 'Definitely!';
@@ -48,7 +47,6 @@ If your choice values are objects, then ``choice_label`` can also be a
             new Status(Status::NO),
             new Status(Status::MAYBE),
         ),
-        'choices_as_values' => true,
         'choice_label' => 'displayName',
     ));
 

reference/forms/types/options/group_by.rst.inc

@@ -22,7 +22,6 @@ Take the following example::
             '1 week' => new \DateTime('+1 week'),
             '1 month' => new \DateTime('+1 month')
         ),
-        'choices_as_values' => true,
         'group_by' => function($val, $key, $index) {
             if ($val <= new \DateTime('+3 days')) {
                 return 'Soon';

reference/forms/types/options/preferred_choices.rst.inc

@@ -17,7 +17,6 @@ you can list the most popular on top, like Bork Bork and Pirate::
             'Bork'   => 'muppets',
             'Pirate' => 'arr'
         ),
-        'choices_as_values' => true,
         'preferred_choices' => array('muppets', 'arr')
     ));
 
@@ -34,7 +33,6 @@ be especially useful if your values are objects::
             '1 week' => new \DateTime('+1 week'),
             '1 month' => new \DateTime('+1 month')
         ),
-        'choices_as_values' => true,
         'preferred_choices' => function ($val, $key) {
             // prefer options within 3 days
             return $val <= new \DateTime('+3 days');