Merge branch '2.8' into 3.3

Author: wouterj

components/finder.rst

@@ -83,7 +83,7 @@ Search in several locations by chaining calls to
 :method:`Symfony\\Component\\Finder\\Finder::in`::
 
     // search inside *both* directories
-    $finder->files()->in(array(__DIR__, '/elsewhere'));
+    $finder->in(array(__DIR__, '/elsewhere'));
 
     // same as above
     $finder->in(__DIR__)->in('/elsewhere');

components/property_access.rst

@@ -314,6 +314,51 @@ see `Enable other Features`_.
 
     var_dump($person->getWouter()); // array(...)
 
+Writing to Array Properties
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The ``PropertyAccessor`` class allows to update the content of arrays stored in
+properties through *adder* and *remover* methods.
+
+.. code-block:: php
+
+    // ...
+    class Person
+    {
+        /**
+         * @var string[]
+         */
+        private $children = array();
+
+        public function getChildren(): array
+        {
+            return $this->children;
+        }
+
+        public function addChild(string $name): void
+        {
+            $this->children[$name] = $name;
+        }
+
+        public function removeChild(string $name): void
+        {
+            unset($this->children[$name]);
+        }
+    }
+
+    $person = new Person();
+    $accessor->setValue($person, 'children', array('kevin', 'wouter'));
+
+    var_dump($person->getChildren()); // array('kevin', 'wouter')
+
+The PropertyAccess component checks for methods called ``add<SingularOfThePropertyName>()``
+and ``remove<SingularOfThePropertyName>()``. Both methods must be defined.
+For instance, in the previous example, the component looks for the ``addChild()``
+and ``removeChild()`` methods to access to the ``children`` property.
+`The Inflector component`_ is used to find the singular of a property name.
+
+If available, *adder* and *remover* methods have priority over a *setter* method.
+
 Checking Property Paths
 -----------------------
 
@@ -407,3 +452,4 @@ Or you can pass parameters directly to the constructor (not the recommended way)
 
 
 .. _Packagist: https://packagist.org/packages/symfony/property-access
+.. _The Inflector component: https://github.com/symfony/inflector

http_cache.rst

@@ -33,7 +33,6 @@ Nottingham's `Cache Tutorial`_.
 .. index::
    single: Cache; Proxy
    single: Cache; Reverse proxy
-   single: Cache; Gateway
 
 .. _gateway-caches:
 
@@ -287,11 +286,15 @@ Safe Methods: Only caching GET or HEAD requests
 HTTP caching only works for "safe" HTTP methods (like GET and HEAD). This means
 two things:
 
-* Don't try to cache PUT, POST or DELETE requests. It won't work and with good
-  reason. These methods are meant to be used when mutating the state of your application
+* Don't try to cache PUT or DELETE requests. It won't work and with good reason.
+  These methods are meant to be used when mutating the state of your application
   (e.g. deleting a blog post). Caching them would prevent certain requests from hitting
   and mutating your application.
 
+* POST requests are generally considered uncachable, but `they can be cached`_
+  when they include explicit freshness information. However POST caching is not
+  widely implemented, so you should avoid it if possible.
+
 * You should *never* change the state of your application (e.g. update a blog post)
   when responding to a GET or HEAD request. If those requests are cached, future
   requests may not actually hit your server.
@@ -367,3 +370,4 @@ Learn more
 .. _`RFC 7234 - Caching`: https://tools.ietf.org/html/rfc7234
 .. _`RFC 7232 - Conditional Requests`: https://tools.ietf.org/html/rfc7232
 .. _`FOSHttpCacheBundle`: http://foshttpcachebundle.readthedocs.org/
+.. _`they can be cached`: https://tools.ietf.org/html/draft-ietf-httpbis-p2-semantics-20#section-2.3.4

reference/constraints/Collection.rst

@@ -310,7 +310,7 @@ error will be returned. If set to ``true``, extra fields are ok.
 extraFieldsMessage
 ~~~~~~~~~~~~~~~~~~
 
-**type**: ``boolean`` **default**: ``The fields {{ fields }} were not expected.``
+**type**: ``boolean`` **default**: ``This field was not expected.``
 
 The message shown if `allowExtraFields`_ is false and an extra field is
 detected.
@@ -328,7 +328,7 @@ option are not present in the underlying collection.
 missingFieldsMessage
 ~~~~~~~~~~~~~~~~~~~~
 
-**type**: ``boolean`` **default**: ``The fields {{ fields }} are missing.``
+**type**: ``boolean`` **default**: ``This field is missing.``
 
 The message shown if `allowMissingFields`_ is false and one or more fields
 are missing from the underlying collection.

reference/constraints/Length.rst

@@ -1,8 +1,13 @@
 Length
 ======
 
-Validates that a given string length is *between* some minimum and maximum
-value.
+Validates that a given string length is *between* some minimum and maximum value.
+
+.. caution::
+
+    ``null`` and empty strings are not handled by this constraint. You need to
+    also add the :doc:`/reference/constraints/NotBlank` or :doc:`/reference/constraints/NotNull`
+    constraints to validate against these.
 
 +----------------+----------------------------------------------------------------------+
 | Applies to     | :ref:`property or method <validation-property-target>`               |

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

@@ -3,16 +3,23 @@ choice_value
 
 **type**: ``callable`` or ``string`` **default**: ``null``
 
-Returns the string "value" for each choice. This is used in the ``value`` attribute
-in HTML and submitted in the POST/PUT requests. You don't normally need to worry
-about this, but it might be handy when processing an API request (since you can
-configure the value that will be sent in the API request).
+Returns the string "value" for each choice, which must be unique across all choices.
+This is used in the ``value`` attribute in HTML and submitted in the POST/PUT requests.
+You don't normally need to worry about this, but it might be handy when processing
+an API request (since you can configure the value that will be sent in the API request).
 
-This can be a callable or a property path. See `choice_label`_ for similar usage.
-If ``null`` is used, an incrementing integer is used as the name.
+This can be a callable or a property path. If ``null`` is given, an incrementing
+integer is used as the value.
 
-If you are using a callable to populate ``choice_value``, you need to check
-for the case that the value of the field may be ``null``.
+If you pass a callable, it will receive one argument: the choice itself. When using
+the :doc:`/reference/forms/types/entity`, the argument will be the entity object
+for each choice or ``null`` in some cases, which you need to handle:
+
+.. code-block:: php
+
+    'choice_value' => function (MyOptionEntity $entity = null) {
+        return $entity ? $entity->getId() : '';
+    },
 
 .. caution::
 

request/load_balancer_reverse_proxy.rst

@@ -2,7 +2,7 @@ How to Configure Symfony to Work behind a Load Balancer or a Reverse Proxy
 ==========================================================================
 
 When you deploy your application, you may be behind a load balancer (e.g.
-an AWS Elastic Load Balancer) or a reverse proxy (e.g. Varnish for
+an AWS Elastic Load Balancing) or a reverse proxy (e.g. Varnish for
 :doc:`caching</http_cache>`).
 
 For the most part, this doesn't cause any problems with Symfony. But, when
@@ -53,7 +53,7 @@ so you can also pass your own value (e.g. ``0b00110``).
 But what if the IP of my Reverse Proxy Changes Constantly!
 ----------------------------------------------------------
 
-Some reverse proxies (like Amazon's Elastic Load Balancers) don't have a
+Some reverse proxies (like AWS Elastic Load Balancing) don't have a
 static IP address or even a range that you can target with the CIDR notation.
 In this case, you'll need to - *very carefully* - trust *all* proxies.
 

security/csrf_in_login_form.rst

@@ -16,7 +16,7 @@ for CSRF. In this article you'll learn how you can use it in your login form.
 Configuring CSRF Protection
 ---------------------------
 
-First, make sure that the CSRF protection is enabled in the main cofiguration
+First, make sure that the CSRF protection is enabled in the main configuration
 file:
 
 .. configuration-block::

service_container.rst

@@ -571,6 +571,20 @@ Actually, once you define a parameter, it can be referenced via the ``%parameter
 syntax in *any* other service configuration file - like ``config.yml``. Many parameters
 are defined in a :ref:`parameters.yml file <config-parameters-yml>`.
 
+You can then fetch the parameter in the service::
+
+    class SiteUpdateManager
+    {
+        // ...
+
+        private $adminEmail;
+
+        public function __construct($adminEmail)
+        {
+            $this->adminEmail = $adminEmail;
+        }
+    }
+
 You can also fetch parameters directly from the container::
 
     public function newAction()

service_container/parameters.rst

@@ -78,8 +78,7 @@ and hidden with the service definition:
 
     .. code-block:: php
 
-        use AppBundle\Service\Mailer;
-        use Symfony\Component\DependencyInjection\Reference;
+        use AppBundle\Mailer;
 
         $container->setParameter('mailer.transport', 'sendmail');