Merge branch '3.2'

* 3.2:
  [#7427] fix line length
  Add apcu cache driver to doctrine config reference
  Change type of arguments min and max
  [#7383] minor rewording
  Added a note about not using the ClassLoader component
  Update guard_authentication.rst
  More clear description of factory service creation
  [#7376] minor wording improvement
  Added a tip about the expanded YAML syntax
  Added a minor help note about Request::setTrustedProxies
  Fix Apache 2.4 UDS instructions
  Fix doc for yaml parameters constants usage
  remove unused options parameter from loadManifest
  Tweaks based on feedback!
  Covering two missing adapters introduced in 3.2
  See #7362 bundles/override > Rewrite translations block

Author: xabbuh

bundles/override.rst

@@ -154,14 +154,11 @@ can override the translations from any translation file, as long as it is in
 
 .. caution::
 
-    The last translation file always wins. That means that you need to make
-    sure that the bundle containing *your* translations is loaded after any
+    Translation files are not aware of :doc:`bundle inheritance </bundles/inheritance>`.
+    If you want to override translations from the parent bundle or another bundle,
+    make sure that the bundle containing *your* translations is loaded after any
     bundle whose translations you're overriding. This is done in ``AppKernel``.
 
-    Translation files are also not aware of :doc:`bundle inheritance </bundles/inheritance>`.
-    If you want to override translations from the parent bundle, be sure that the
-    parent bundle is loaded before the child bundle in the ``AppKernel`` class.
-
-    The file that always wins is the one that is placed in
-    ``app/Resources/translations``, as those files are always loaded last.
+    Finally, translations located in ``app/Resources/translations`` will override
+    all the other translations since those files are always loaded last.
 .. _`the Doctrine documentation`: http://docs.doctrine-project.org/projects/doctrine-orm/en/latest/reference/inheritance-mapping.html#overrides

components/cache/cache_pools.rst

@@ -58,6 +58,25 @@ contents as regular files in a set of directories on the local file system::
         $directory = null
     );
 
+Php Files Cache Adapter
+~~~~~~~~~~~~~~~~~~~~~~~
+
+This adapter is very similar to the Filesystem adapter, except that the saving creates
+a ``.php`` file, which is included on fetch (allowing the file to be saved in OPcache)::
+
+    use Symfony\Component\Cache\Adapter\PhpFilesAdapter;
+
+    $cache = new PhpFilesAdapter(
+        // the subdirectory of the main cache directory where cache items are stored
+        $namespace = '',
+        // in seconds; applied to cache items that don't define their own lifetime
+        // 0 means to store the cache items indefinitely (i.e. until the files are deleted)
+        $defaultLifetime = 0,
+        // the main cache directory (the application needs read-write permissions on it)
+        // if none is specified, a directory is created inside the system temporary directory
+        $directory = null
+    );
+
 APCu Cache Adapter
 ~~~~~~~~~~~~~~~~~~
 
@@ -189,6 +208,41 @@ This adapter also defines two optional arguments called  ``namespace`` (default:
 ``''``) and ``defaultLifetime`` (default: ``0``) and adapts them to make them
 work in the underlying Doctrine cache.
 
+Php Array Cache Adapter
+~~~~~~~~~~~~~~~~~~~~~~~
+
+This adapter is a highly performant way to cache static data (e.g. application configuration)
+that is optimized and preloaded into OPcache memory storage::
+
+    use Symfony\Component\Cache\Adapter\PhpArrayAdapter;
+    use Symfony\Component\Cache\Adapter\PhpFilesAdapter;
+
+    // somehow, decide it's time to warm up the cache!
+    if ($needsWarmup) {
+        // some static values
+        $values = array(
+            'stats.num_products' => 4711,
+            'stats.num_users' => 1356,
+        );
+
+        $cache = new PhpArrayAdapter(
+            // single file where values are cached
+            __DIR__ . '/somefile.cache',
+            // a backup adapter, if you set values after warmup
+            new FilesystemAdapter()
+        );
+        $cache->warmUp($values);
+    }
+
+    // ... then, use the cache!
+    $cacheItem = $cache->getItem('stats.num_users');
+    echo $cacheItem->get();
+
+.. note::
+
+    This adapter requires PHP 7.x and should be used with the php.ini setting
+    ``opcache.enable`` on.
+
 Looking for Cache Items
 -----------------------
 

components/class_loader.rst

@@ -7,6 +7,11 @@ The ClassLoader Component
     The ClassLoader component provides tools to autoload your classes and
     cache their locations for performance.
 
+.. caution::
+
+    The ClassLoader component was deprecated in Symfony 3.3 and it will be
+    removed in 4.0. As an alternative, use Composer's class loading mechanism.
+
 Usage
 -----
 

components/http_foundation/trusting_proxies.rst

@@ -17,15 +17,20 @@ the actual host may be stored in an ``X-Forwarded-Host`` header.
 
 Since HTTP headers can be spoofed, Symfony does *not* trust these proxy
 headers by default. If you are behind a proxy, you should manually whitelist
-your proxy.
+your proxy as follows:
 
 .. code-block:: php
 
     use Symfony\Component\HttpFoundation\Request;
 
-    // only trust proxy headers coming from this IP addresses
+    // put this code as early as possible in your application (e.g. in your
+    // front controller) to only trust proxy headers coming from these IP addresses
     Request::setTrustedProxies(array('192.0.0.1', '10.0.0.0/8'));
 
+.. versionadded:: 2.3
+    CIDR notation support was introduced in Symfony 2.3, so you can whitelist whole
+    subnets (e.g. ``10.0.0.0/8``, ``fc00::/7``).
+
 You should also make sure that your proxy filters unauthorized use of these
 headers, e.g. if a proxy natively uses the ``X-Forwarded-For`` header, it
 should not allow clients to send ``Forwarded`` headers to Symfony.

frontend/custom_version_strategy.rst

@@ -100,7 +100,7 @@ version string::
             return $versionized;
         }
 
-        private function loadManifest(array $options)
+        private function loadManifest()
         {
             return json_decode(file_get_contents($this->manifestPath), true);
         }

reference/configuration/doctrine.rst

@@ -297,8 +297,9 @@ certain classes, but those are for very advanced use-cases only.
 Caching Drivers
 ~~~~~~~~~~~~~~~
 
-For the caching drivers you can specify the values ``array``, ``apc``, ``memcache``,
-``memcached``, ``redis``, ``wincache``, ``zenddata``, ``xcache`` or ``service``.
+For the caching drivers you can specify the values ``array``, ``apc``, ``apcu``,
+``memcache``, ``memcached``, ``redis``, ``wincache``, ``zenddata``, ``xcache``
+or ``service``.
 
 The following example shows an overview of the caching configurations:
 

reference/constraints/Count.rst

@@ -38,8 +38,8 @@ you might add the following:
         {
             /**
              * @Assert\Count(
-             *      min = "1",
-             *      max = "5",
+             *      min = 1,
+             *      max = 5,
              *      minMessage = "You must specify at least one email",
              *      maxMessage = "You cannot specify more than {{ limit }} emails"
              * )

security/guard_authentication.rst

@@ -502,8 +502,10 @@ Frequently Asked Questions
                         logout: ~
 
                         guard:
+                            entry_point: app.form_login_authenticator
                             authenticators:
                                 - app.token_authenticator
+                                - app.form_login_authenticator
 
                         # if you want, disable storing the user in the session
                         # stateless: true
@@ -529,8 +531,9 @@ Frequently Asked Questions
                     >
                         <logout />
 
-                        <guard>
+                        <guard entry-point="app.form_login_authenticator">
                             <authenticator>app.token_authenticator</authenticator>
+                            <authenticator>app.form_login_authenticator</authenticator>
                         </guard>
 
                         <!-- ... -->
@@ -551,8 +554,10 @@ Frequently Asked Questions
                         'anonymous'      => true,
                         'logout'         => true,
                         'guard'          => array(
+                            'entry_point'     => 'app.form_login_authenticator',
                             'authenticators'  => array(
-                                'app.token_authenticator'
+                                'app.token_authenticator',
+                                'app.form_login_authenticator',
                             ),
                         ),
                         // ...

service_container.rst

@@ -462,6 +462,29 @@ Injecting the dependency by the setter method just needs a change of syntax:
     and "setter injection". The Symfony service container also supports
     "property injection".
 
+.. tip::
+
+    The YAML configuration format supports an expanded syntax which may be
+    useful when the YAML contents are long and complex:
+
+    .. code-block:: yaml
+
+        # app/config/services.yml
+        services:
+            # traditional syntax
+            app.newsletter_manager:
+                class: AppBundle\Newsletter\NewsletterManager
+                calls:
+                    - [setMailer, ['@app.mailer']]
+
+            # expanded syntax
+            app.newsletter_manager:
+                class: AppBundle\Newsletter\NewsletterManager
+                calls:
+                    - method: setMailer
+                      arguments:
+                          - '@app.mailer'
+
 Learn more
 ----------