Merge branch '2.8' into 3.1

xabbuh · xabbuh · commit a6386100a27d · 2017-02-03T17:11:38.000+01:00
* 2.8: [symfony#7427] fix line length Add apcu cache driver to doctrine config reference Change type of arguments min and max [symfony#7383] minor rewording Added a note about not using the ClassLoader component Update guard_authentication.rst More clear description of factory service creation [symfony#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 See symfony#7362 bundles/override > Rewrite translations block
diff --git a/bundles/override.rst b/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
diff --git a/components/class_loader.rst b/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
 -----
 
diff --git a/components/http_foundation/trusting_proxies.rst b/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.
diff --git a/reference/configuration/doctrine.rst b/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:
 
diff --git a/reference/constraints/Count.rst b/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"
              * )
diff --git a/security/guard_authentication.rst b/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',
                             ),
                         ),
                         // ...
diff --git a/service_container.rst b/service_container.rst
@@ -456,6 +456,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
 ----------
 
diff --git a/service_container/factories.rst b/service_container/factories.rst
@@ -13,9 +13,9 @@ the service container to call a method on the factory rather than directly
 instantiating the class.
 
 Suppose you have a factory that configures and returns a new ``NewsletterManager``
-object::
+object by calling the static ``createNewsletterManager()`` method::
 
-    class NewsletterManagerFactory
+    class NewsletterManagerStaticFactory
     {
         public static function createNewsletterManager()
         {
@@ -29,45 +29,98 @@ object::
 
 To make the ``NewsletterManager`` object available as a service, you can
 configure the service container to use the
-``NewsletterManagerFactory::createNewsletterManager()`` factory method:
+``NewsletterManagerStaticFactory::createNewsletterManager()`` factory method:
 
 .. configuration-block::
 
     .. code-block:: yaml
 
+        # app/config/services.yml
+
         services:
             app.newsletter_manager:
                 class:   AppBundle\Email\NewsletterManager
-                # call a static method
-                factory: ['AppBundle\Email\NewsletterManager', create]
+                # call the static method
+                factory: ['AppBundle\Email\NewsletterManagerStaticFactory', createNewsletterManager]
+
+    .. code-block:: xml
+
+        <!-- app/config/services.xml -->
+
+        <?xml version="1.0" encoding="UTF-8" ?>
+        <container xmlns="http://symfony.com/schema/dic/services"
+            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+            xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd">
+
+            <services>
+                <service id="app.newsletter_manager" class="AppBundle\Email\NewsletterManager">
+                    <!-- call the static method -->
+                    <factory class="AppBundle\Email\NewsletterManagerStaticFactory" method="createNewsletterManager" />
+                </service>
+            </services>
+        </container>
+
+    .. code-block:: php
+
+        // app/config/services.php
+
+        use AppBundle\Email\NewsletterManager;
+        use AppBundle\Email\NewsletterManagerStaticFactory;
+        use Symfony\Component\DependencyInjection\Definition;
+        // ...
+
+        $definition = new Definition(NewsletterManager::class);
+        // call the static method
+        $definition->setFactory(array(NewsletterManagerStaticFactory::class, 'createNewsletterManager'));
+
+        $container->setDefinition('app.newsletter_manager', $definition);
+
+.. note::
+
+    When using a factory to create services, the value chosen for the ``class``
+    option has no effect on the resulting service. The actual class name
+    only depends on the object that is returned by the factory. However,
+    the configured class name may be used by compiler passes and therefore
+    should be set to a sensible value.
+
+If your factory is not using a static function to configure and create your
+service, but a regular method, you can instantiate the factory itself as a
+service too. Later, in the ":ref:`factories-passing-arguments-factory-method`"
+section, you learn how you can inject arguments in this method.
+
+Configuration of the service container then looks like this:
+
+.. configuration-block::
+
+    .. code-block:: yaml
 
+        # app/config/services.yml
+
+        services:
             app.newsletter_manager_factory:
                 class: AppBundle\Email\NewsletterManagerFactory
 
             app.newsletter_manager:
                 class:   AppBundle\Email\NewsletterManager
-                # call a method on the specified service
+                # call a method on the specified factory service
                 factory: 'app.newsletter_manager_factory:createNewsletterManager'
 
     .. code-block:: xml
 
+        <!-- app/config/services.xml -->
+
         <?xml version="1.0" encoding="UTF-8" ?>
         <container xmlns="http://symfony.com/schema/dic/services"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd">
 
             <services>
-                <service id="app.newsletter_manager" class="AppBundle\Email\NewsletterManager">
-                    <!-- call a static method -->
-                    <factory class="AppBundle\Email\NewsletterManager" method="create" />
-                </service>
-
                 <service id="app.newsletter_manager_factory"
                     class="AppBundle\Email\NewsletterManagerFactory"
                 />
 
                 <service id="app.newsletter_manager" class="AppBundle\Email\NewsletterManager">
-                    <!-- call a method on the specified service -->
+                    <!-- call a method on the specified factory service -->
                     <factory service="app.newsletter_manager_factory"
                         method="createNewsletterManager"
                     />
@@ -77,50 +130,42 @@ configure the service container to use the
 
     .. code-block:: php
 
+        // app/config/services.php
+
         use AppBundle\Email\NewsletterManager;
         use AppBundle\Email\NewsletterManagerFactory;
         use Symfony\Component\DependencyInjection\Definition;
         // ...
 
-        $definition = new Definition(NewsletterManager::class);
-        // call a static method
-        $definition->setFactory(array(NewsletterManager::class, 'create'));
-
-        $container->setDefinition('app.newsletter_manager', $definition);
-
         $container->register('app.newsletter_manager_factory', NewsletterManagerFactory::class);
 
         $newsletterManager = new Definition(NewsletterManager::class);
 
-        // call a method on the specified service
+        // call a method on the specified factory service
         $newsletterManager->setFactory(array(
             new Reference('app.newsletter_manager_factory'),
             'createNewsletterManager'
         ));
 
         $container->setDefinition('app.newsletter_manager', $newsletterManager);
 
-.. note::
-
-    When using a factory to create services, the value chosen for the ``class``
-    option has no effect on the resulting service. The actual class name
-    only depends on the object that is returned by the factory. However,
-    the configured class name may be used by compiler passes and therefore
-    should be set to a sensible value.
-
 .. note::
 
     The traditional configuration syntax in YAML files used an array to define
     the factory service and the method name:
 
     .. code-block:: yaml
 
+        # app/config/services.yml
+
         app.newsletter_manager:
             # new syntax
             factory: 'app.newsletter_manager_factory:createNewsletterManager'
             # old syntax
             factory: ['@app.newsletter_manager_factory', createNewsletterManager]
 
+.. _factories-passing-arguments-factory-method:
+
 Passing Arguments to the Factory Method
 ---------------------------------------
 
@@ -132,6 +177,8 @@ method in the previous example takes the ``templating`` service as an argument:
 
     .. code-block:: yaml
 
+        # app/config/services.yml
+
         services:
             # ...
 
@@ -142,6 +189,8 @@ method in the previous example takes the ``templating`` service as an argument:
 
     .. code-block:: xml
 
+        <!-- app/config/services.xml -->
+
         <?xml version="1.0" encoding="UTF-8" ?>
         <container xmlns="http://symfony.com/schema/dic/services"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
@@ -159,6 +208,8 @@ method in the previous example takes the ``templating`` service as an argument:
 
     .. code-block:: php
 
+        // app/config/services.php
+
         use AppBundle\Email\NewsletterManager;
         use Symfony\Component\DependencyInjection\Reference;
         use Symfony\Component\DependencyInjection\Definition;
diff --git a/setup/web_server_configuration.rst b/setup/web_server_configuration.rst
@@ -162,10 +162,9 @@ Using mod_proxy_fcgi with Apache 2.4
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 If you are running Apache 2.4, you can easily use ``mod_proxy_fcgi`` to pass
-incoming requests to PHP-FPM. Configure PHP-FPM to listen on a TCP socket
-(``mod_proxy`` currently `does not support Unix sockets`_), enable ``mod_proxy``
-and ``mod_proxy_fcgi`` in your Apache configuration and use the ``SetHandler``
-directive to pass requests for PHP files to PHP FPM:
+incoming requests to PHP-FPM. Configure PHP-FPM to listen on a TCP or Unix socket,
+enable ``mod_proxy`` and ``mod_proxy_fcgi`` in your Apache configuration, and
+use the ``SetHandler`` directive to pass requests for PHP files to PHP FPM:
 
 .. code-block:: apache
 
@@ -183,6 +182,8 @@ directive to pass requests for PHP files to PHP FPM:
         # with mod_rewrite or mod_autoindex
         <FilesMatch \.php$>
             SetHandler proxy:fcgi://127.0.0.1:9000
+            # for Unix sockets, Apache 2.4.10 or higher
+            # SetHandler proxy:unix:/path/to/fpm.sock|fcgi://dummy
         </FilesMatch>
 
         # If you use Apache version below 2.4.9 you must consider update or use this instead
@@ -338,6 +339,5 @@ The **minimum configuration** to get your application running under Nginx is:
 For advanced Nginx configuration options, read the official `Nginx documentation`_.
 
 .. _`Apache documentation`: http://httpd.apache.org/docs/
-.. _`does not support Unix sockets`: https://bz.apache.org/bugzilla/show_bug.cgi?id=54101
 .. _`FastCgiExternalServer`: http://www.fastcgi.com/mod_fastcgi/docs/mod_fastcgi.html#FastCgiExternalServer
 .. _`Nginx documentation`: http://wiki.nginx.org/Symfony
