erge remote-tracking branch 'upstream/3.3' into 3.3

javiereguiluz · javiereguiluz · commit 6fac6c253fd8 · 2017-10-11T15:47:06.000+02:00
diff --git a/components/finder.rst b/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');
diff --git a/components/property_access.rst b/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
diff --git a/frontend/encore/bootstrap.rst b/frontend/encore/bootstrap.rst
@@ -35,14 +35,14 @@ file into ``global.scss``. You can even customize the Bootstrap variables first!
     in the ``bootstrap`` directory instead - e.g. ``~bootstrap-sass/assets/stylesheets/bootstrap/alerts``.
 
 After including ``bootstrap-sass``, your Webpack builds might become slow. To fix
-this, you can use the ``resolve_url_loader`` option:
+this, you can use the ``resolveUrlLoader`` option:
 
 .. code-block:: diff
 
     // webpack.config.js
     Encore
     +     .enableSassLoader(function(sassOptions) {}, {
-    +         resolve_url_loader: false
+    +         resolveUrlLoader: false
     +     })
     ;
 
diff --git a/frontend/encore/shared-entry.rst b/frontend/encore/shared-entry.rst
@@ -32,7 +32,7 @@ on your page before any other JavaScript file:
 .. code-block:: twig
 
     <!-- these two files now must be included in every page -->
-    <script src="{{ asset('build/manifest.js') }}"></script>
+    <script src="{{ asset('build/manifest.json') }}"></script>
     <script src="{{ asset('build/vendor.js') }}"></script>
 
     <!-- here you link to the specific JS files needed by the current page -->
@@ -42,7 +42,7 @@ on your page before any other JavaScript file:
     <link rel="stylesheet" href="{{ asset('build/vendor.css') }}" />
 
 The ``vendor.js`` file contains all the common code that has been extracted from
-the other files, so it's obvious that it must be included. The other file (``manifest.js``)
+the other files, so it's obvious that it must be included. The other file (``manifest.json``)
 is less obvious: it's needed so that Webpack knows how to load those shared modules.
 
 .. tip::
diff --git a/frontend/encore/simple-example.rst b/frontend/encore/simple-example.rst
@@ -72,7 +72,7 @@ To build the assets, use the ``encore`` executable:
 
     # shorter version of the above 3 commands
     $ yarn run encore dev
-    $ yarn run encore dev -- --watch
+    $ yarn run encore dev --watch
     $ yarn run encore production
 
 .. note::
diff --git a/http_cache.rst b/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
diff --git a/reference/constraints/Collection.rst b/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.
diff --git a/reference/constraints/Length.rst b/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>`               |
diff --git a/reference/forms/types/options/choice_value.rst.inc b/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::
 
diff --git a/request/load_balancer_reverse_proxy.rst b/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.
 
diff --git a/security/csrf_in_login_form.rst b/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::
diff --git a/service_container.rst b/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()
@@ -843,9 +857,9 @@ key. For example, the default Symfony configuration contains this:
 
             # the namespace prefix for classes (must end in \)
             AppBundle\:
-                # accepts a glob pattern
+                # create services for all the classes found in this directory...
                 resource: '../../src/AppBundle/*'
-                # exclude some paths
+                # ...except for the classes located in these directories
                 exclude: '../../src/AppBundle/{Entity,Repository}'
 
             # these were imported above, but we want to add some extra config
@@ -900,6 +914,11 @@ key. For example, the default Symfony configuration contains this:
         // $this is a reference to the current loader
         $this->registerClasses($definition, 'AppBundle\\Controller\\', '../../src/AppBundle/Controller/*');
 
+.. tip::
+
+    The value of the ``resource`` and ``exclude`` options can be any valid
+    `glob pattern`_.
+
 This can be used to quickly make many classes available as services and apply some
 default configuration. The ``id`` of each service is its fully-qualified class name.
 You can override any service that's imported by using its id (class name) below
@@ -1043,3 +1062,4 @@ Learn more
 
 .. _`service-oriented architecture`: https://en.wikipedia.org/wiki/Service-oriented_architecture
 .. _`Symfony Standard Edition (version 3.3) services.yml`: https://github.com/symfony/symfony-standard/blob/3.3/app/config/services.yml
+.. _`glob pattern`: https://en.wikipedia.org/wiki/Glob_(programming)
diff --git a/service_container/parameters.rst b/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');
 
diff --git a/templating.rst b/templating.rst
@@ -6,7 +6,7 @@ Creating and Using Templates
 
 As explained in :doc:`the previous article </controller>`, controllers are
 responsible for handling each request that comes into a Symfony application and
-the usually end up rendering a template to generate the response contents.
+they usually end up rendering a template to generate the response contents.
 
 In reality, the controller delegates most of the heavy work to other places so
 that code can be tested and reused. When a controller needs to generate HTML,
diff --git a/validation/custom_constraint.rst b/validation/custom_constraint.rst
@@ -45,7 +45,7 @@ includes some simple default logic::
     // in the base Symfony\Component\Validator\Constraint class
     public function validatedBy()
     {
-        return ContainsAlphanumericValidator::class;
+        return get_class($this).'Validator';
     }
 
 In other words, if you create a custom ``Constraint`` (e.g. ``MyConstraint``),
diff --git a/workflow/usage.rst b/workflow/usage.rst
@@ -125,7 +125,7 @@ like this:
                              'from' => 'review',
                              'to' => 'published',
                          ),
-                         'reject'=> array(
+                         'reject' => array(
                              'from' => 'review',
                              'to' => 'rejected',
                          ),
