Merge branch '4.1'

* 4.1: (31 commits)
  Documented the false_values option of checkbox types
  Added the versionadded directive
  Update the documentation for Symfony Flex
  Improved the multiple user providers article
  Reowrd to restore the original meaning
  Removed a no longer relevant text
  Update NotBlank constraint description
  add missing argument binding section
  Added a minor note about Composer's plaform config
  Documented the use of binary values as container params
  Documented the support of iterators in write() and writeln()
  Update 3.3-di-changes.rst
  ...

Author: javiereguiluz

components/http_foundation/session_configuration.rst

@@ -73,6 +73,7 @@ easily serve as examples if you wish to write your own.
 
 * :class:`Symfony\\Component\\HttpFoundation\\Session\\Storage\\Handler\\PdoSessionHandler`
 * :class:`Symfony\\Component\\HttpFoundation\\Session\\Storage\\Handler\\MemcachedSessionHandler`
+* :class:`Symfony\\Component\\HttpFoundation\\Session\\Storage\\Handler\\MigratingSessionHandler`
 * :class:`Symfony\\Component\\HttpFoundation\\Session\\Storage\\Handler\\RedisSessionHandler`
 * :class:`Symfony\\Component\\HttpFoundation\\Session\\Storage\\Handler\\MongoDbSessionHandler`
 * :class:`Symfony\\Component\\HttpFoundation\\Session\\Storage\\Handler\\NullSessionHandler`
@@ -87,6 +88,32 @@ Example usage::
     $sessionStorage = new NativeSessionStorage(array(), new PdoSessionHandler($pdo));
     $session = new Session($sessionStorage);
 
+Migrating Between Save Handlers
+-------------------------------
+
+.. versionadded:: 4.1
+    The ``MigratingSessionHandler`` class was introduced in Symfony 4.1.
+
+If your application changes the way sessions are stored, use the
+:class:`Symfony\\Component\\HttpFoundation\\Session\\Storage\\Handler\\MigratingSessionHandler`
+to migrate between old and new save handlers without losing session data.
+
+This is the recommended migration workflow:
+
+#. Switch to the migrating handler, with your new handler as the write-only one.
+   The old handler behaves as usual and sessions get written to the new one::
+
+       $sessionStorage = new MigratingSessionHandler($oldSessionStorage, $newSessionStorage);
+
+#. After your session gc period, verify that the data in the new handler is correct.
+#. Update the migrating handler to use the old handler as the write-only one, so
+   the sessions will now be read from the new handler. This step allows easier rollbacks::
+
+       $sessionStorage = new MigratingSessionHandler($newSessionStorage, $oldSessionStorage);
+
+#. After verifying that the sessions in your application are working, switch
+   from the migrating handler to the new handler.
+
 Configuring PHP Sessions
 ~~~~~~~~~~~~~~~~~~~~~~~~
 

console.rst

@@ -101,6 +101,10 @@ messages to the console)::
             '',
         ]);
 
+        // the value returned by someMethod() can be an iterator (https://secure.php.net/iterator)
+        // that generates and returns the messages with the 'yield' PHP keyword
+        $output->writeln($this->someMethod());
+
         // outputs a message followed by a "\n"
         $output->writeln('Whoa!');
 
@@ -109,6 +113,10 @@ messages to the console)::
         $output->write('create a user.');
     }
 
+.. versionadded:: 4.1
+    The support of PHP iterators in the ``write()`` and ``writeln()`` methods
+    was introduced in Symfony 4.1.
+
 Now, try executing the command:
 
 .. code-block:: terminal

console/request_context.rst

@@ -21,8 +21,8 @@ Configuring the Request Context Globally
 
 To configure the Request Context - which is used by the URL Generator - you can
 redefine the parameters it uses as default values to change the default host
-(``localhost``) and scheme (``http``). You can also configure the base path if
-Symfony is not running in the root directory.
+(``localhost``) and scheme (``http``). You can also configure the base path (both for
+the URL generator and the assets) if Symfony is not running in the root directory.
 
 Note that this does not impact URLs generated via normal web requests, since those
 will override the defaults.
@@ -36,6 +36,8 @@ will override the defaults.
             router.request_context.host: example.org
             router.request_context.scheme: https
             router.request_context.base_url: my/path
+            asset.request_context.base_path: %router.request_context.base_url%
+            asset.request_context.secure: true
 
     .. code-block:: xml
 
@@ -48,6 +50,8 @@ will override the defaults.
                 <parameter key="router.request_context.host">example.org</parameter>
                 <parameter key="router.request_context.scheme">https</parameter>
                 <parameter key="router.request_context.base_url">my/path</parameter>
+                <parameter key="asset.request_context.base_path">%router.request_context.base_url%</parameter>
+                <parameter key="asset.request_context.secure">true</parameter>
             </parameters>
 
         </container>
@@ -58,6 +62,11 @@ will override the defaults.
         $container->setParameter('router.request_context.host', 'example.org');
         $container->setParameter('router.request_context.scheme', 'https');
         $container->setParameter('router.request_context.base_url', 'my/path');
+        $container->setParameter('asset.request_context.base_path', $container->getParameter('router.request_context.base_url'));
+        $container->setParameter('asset.request_context.secure', true);
+
+.. versionadded:: 3.4
+    The ``asset.request_context.*`` parameters were introduced in Symfony 3.4.
 
 Configuring the Request Context per Command
 -------------------------------------------

contributing/code/security.rst

@@ -37,7 +37,6 @@ confirmed, the core team works on a solution following these steps:
 #. Package new versions for all affected versions;
 #. Publish the post on the official Symfony `blog`_ (it must also be added to
    the "`Security Advisories`_" category);
-#. Update the security advisory list (see below).
 #. Update the public `security advisories database`_ maintained by the
    FriendsOfPHP organization and which is used by the ``security:check`` command.
 
@@ -100,47 +99,13 @@ Security Advisories
     You can check your Symfony application for known security vulnerabilities
     using the ``security:check`` command (see :doc:`/security/security_checker`).
 
-This section indexes security vulnerabilities that were fixed in Symfony
-releases, starting from Symfony 1.0.0:
-
-* Jul 17, 2017, `CVE-2017-11365: Empty passwords validation issue <https://symfony.com/blog/cve-2017-11365-empty-passwords-validation-issue>`_ (2.7.30, 2.7.31, 2.8.23, 2.8.24, 3.2.10, 3.2.11, 3.3.3, and 3.3.4)
-* May 9, 2016: `CVE-2016-2403: Unauthorized access on a misconfigured Ldap server when using an empty password <https://symfony.com/blog/cve-2016-2403-unauthorized-access-on-a-misconfigured-ldap-server-when-using-an-empty-password>`_ (2.8.0-2.8.5, 3.0.0-3.0.5)
-* May 9, 2016: `CVE-2016-4423: Large username storage in session <https://symfony.com/blog/cve-2016-4423-large-username-storage-in-session>`_ (2.3.0-2.3.40, 2.7.0-2.7.12, 2.8.0-2.8.5, 3.0.0-3.0.5)
-* January 18, 2016: `CVE-2016-1902: SecureRandom's fallback not secure when OpenSSL fails <https://symfony.com/blog/cve-2016-1902-securerandom-s-fallback-not-secure-when-openssl-fails>`_ (2.3.0-2.3.36, 2.6.0-2.6.12, 2.7.0-2.7.8)
-* November 23, 2015: `CVE-2015-8125: Potential Remote Timing Attack Vulnerability in Security Remember-Me Service <https://symfony.com/blog/cve-2015-8125-potential-remote-timing-attack-vulnerability-in-security-remember-me-service>`_ (2.3.35, 2.6.12 and 2.7.7)
-* November 23, 2015: `CVE-2015-8124: Session Fixation in the "Remember Me" Login Feature <https://symfony.com/blog/cve-2015-8124-session-fixation-in-the-remember-me-login-feature>`_ (2.3.35, 2.6.12 and 2.7.7)
-* May 26, 2015: `CVE-2015-4050: ESI unauthorized access <https://symfony.com/blog/cve-2015-4050-esi-unauthorized-access>`_ (Symfony 2.3.29, 2.5.12 and 2.6.8)
-* April 1, 2015: `CVE-2015-2309: Unsafe methods in the Request class <https://symfony.com/blog/cve-2015-2309-unsafe-methods-in-the-request-class>`_ (Symfony 2.3.27, 2.5.11 and 2.6.6)
-* April 1, 2015: `CVE-2015-2308: Esi Code Injection <https://symfony.com/blog/cve-2015-2308-esi-code-injection>`_ (Symfony 2.3.27, 2.5.11 and 2.6.6)
-* September 3, 2014: `CVE-2014-6072: CSRF vulnerability in the Web Profiler <https://symfony.com/blog/cve-2014-6072-csrf-vulnerability-in-the-web-profiler>`_ (Symfony 2.3.19, 2.4.9 and 2.5.4)
-* September 3, 2014: `CVE-2014-6061: Security issue when parsing the Authorization header <https://symfony.com/blog/cve-2014-6061-security-issue-when-parsing-the-authorization-header>`_ (Symfony 2.3.19, 2.4.9 and 2.5.4)
-* September 3, 2014: `CVE-2014-5245: Direct access of ESI URLs behind a trusted proxy <https://symfony.com/blog/cve-2014-5245-direct-access-of-esi-urls-behind-a-trusted-proxy>`_ (Symfony 2.3.19, 2.4.9 and 2.5.4)
-* September 3, 2014: `CVE-2014-5244: Denial of service with a malicious HTTP Host header <https://symfony.com/blog/cve-2014-5244-denial-of-service-with-a-malicious-http-host-header>`_ (Symfony 2.3.19, 2.4.9 and 2.5.4)
-* July 15, 2014: `Security releases: Symfony 2.3.18, 2.4.8, and 2.5.2 released <https://symfony.com/blog/security-releases-cve-2014-4931-symfony-2-3-18-2-4-8-and-2-5-2-released>`_ (`CVE-2014-4931 <http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2014-4931>`_)
-* October 10, 2013: `Security releases: Symfony 2.0.25, 2.1.13, 2.2.9, and 2.3.6 released <https://symfony.com/blog/security-releases-cve-2013-5958-symfony-2-0-25-2-1-13-2-2-9-and-2-3-6-released>`_ (`CVE-2013-5958 <http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2013-5958>`_)
-* August 7, 2013: `Security releases: Symfony 2.0.24, 2.1.12, 2.2.5, and 2.3.3 released <https://symfony.com/blog/security-releases-symfony-2-0-24-2-1-12-2-2-5-and-2-3-3-released>`_ (`CVE-2013-4751 <http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2013-4751>`_ and `CVE-2013-4752 <http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2013-4752>`_)
-* January 17, 2013: `Security release: Symfony 2.0.22 and 2.1.7 released <https://symfony.com/blog/security-release-symfony-2-0-22-and-2-1-7-released>`_ (`CVE-2013-1348 <http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2013-1348>`_ and `CVE-2013-1397 <http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2013-1397>`_)
-* December 20, 2012: `Security release: Symfony 2.0.20 and 2.1.5 <https://symfony.com/blog/security-release-symfony-2-0-20-and-2-1-5-released>`_  (`CVE-2012-6431 <http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2012-6431>`_ and `CVE-2012-6432 <http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2012-6432>`_)
-* November 29, 2012: `Security release: Symfony 2.0.19 and 2.1.4 <https://symfony.com/blog/security-release-symfony-2-0-19-and-2-1-4>`_
-* November 25, 2012: `Security release: symfony 1.4.20 released  <https://symfony.com/blog/security-release-symfony-1-4-20-released>`_ (`CVE-2012-5574 <http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2012-5574>`_)
-* August 28, 2012: `Security Release: Symfony 2.0.17 released <https://symfony.com/blog/security-release-symfony-2-0-17-released>`_
-* May 30, 2012: `Security Release: symfony 1.4.18 released <https://symfony.com/blog/security-release-symfony-1-4-18-released>`_ (`CVE-2012-2667 <http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2012-2667>`_)
-* February 24, 2012: `Security Release: Symfony 2.0.11 released <https://symfony.com/blog/security-release-symfony-2-0-11-released>`_
-* November 16, 2011: `Security Release: Symfony 2.0.6 <https://symfony.com/blog/security-release-symfony-2-0-6>`_
-* March 21, 2011: `symfony 1.3.10 and 1.4.10: security releases <https://symfony.com/blog/symfony-1-3-10-and-1-4-10-security-releases>`_
-* June 29, 2010: `Security Release: symfony 1.3.6 and 1.4.6 <https://symfony.com/blog/security-release-symfony-1-3-6-and-1-4-6>`_
-* May 31, 2010: `symfony 1.3.5 and 1.4.5 <https://symfony.com/blog/symfony-1-3-5-and-1-4-5>`_
-* February 25, 2010: `Security Release: 1.2.12, 1.3.3 and 1.4.3 <https://symfony.com/blog/security-release-1-2-12-1-3-3-and-1-4-3>`_
-* February 13, 2010: `symfony 1.3.2 and 1.4.2 <https://symfony.com/blog/symfony-1-3-2-and-1-4-2>`_
-* April 27, 2009: `symfony 1.2.6: Security fix <https://symfony.com/blog/symfony-1-2-6-security-fix>`_
-* October 03, 2008: `symfony 1.1.4 released: Security fix <https://symfony.com/blog/symfony-1-1-4-released-security-fix>`_
-* May 14, 2008: `symfony 1.0.16 is out  <https://symfony.com/blog/symfony-1-0-16-is-out>`_
-* April 01, 2008: `symfony 1.0.13 is out  <https://symfony.com/blog/symfony-1-0-13-is-out>`_
-* March 21, 2008: `symfony 1.0.12 is (finally) out ! <https://symfony.com/blog/symfony-1-0-12-is-finally-out>`_
-* June 25, 2007: `symfony 1.0.5 released (security fix) <https://symfony.com/blog/symfony-1-0-5-released-security-fix>`_
+Check the `Security Advisories`_ blog category for a list of all security
+vulnerabilities that were fixed in Symfony releases, starting from Symfony
+1.0.0.
 
 .. _Git repository: https://github.com/symfony/symfony
 .. _blog: https://symfony.com/blog/
 .. _Security Advisories: https://symfony.com/blog/category/security-advisories
 .. _`security advisories database`: https://github.com/FriendsOfPHP/security-advisories
 .. _`mitre.org`: https://cveform.mitre.org/
+.. _`Security Advisories`: https://symfony.com/blog/category/security-advisories

messenger.rst

@@ -605,6 +605,116 @@ you can disable them like this:
             ),
         ));
 
+Using Middleware Factories
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Some third-party bundles and libraries provide configurable middleware via
+factories. Using them requires a two-step configuration based on Symfony's
+:doc:`dependency injection </service_container>` features:
+
+.. code-block:: yaml
+
+    services:
+
+        # Step 1: a factory class is registered as a service with the required
+        # dependencies to instantiate a middleware
+        doctrine.orm.messenger.middleware_factory.transaction:
+            class: Symfony\Bridge\Doctrine\Messenger\DoctrineTransactionMiddlewareFactory
+            arguments: ['@doctrine']
+
+        # Step 2: an abstract definition that will call the factory with default
+        # arguments or the one provided in the middleware config
+        messenger.middleware.doctrine_transaction_middleware:
+            class: Symfony\Bridge\Doctrine\Messenger\DoctrineTransactionMiddleware
+            factory: ['@doctrine.orm.messenger.middleware_factory.transaction', 'createMiddleware']
+            abstract: true
+            # the default arguments to use when none provided from config. Example:
+            # middleware:
+            #     - doctrine_transaction_middleware: ~
+            arguments: ['default']
+
+The "default" value in this example is the name of the entity manager to use,
+which is the argument expected by the
+``Symfony\Bridge\Doctrine\Messenger\DoctrineTransactionMiddlewareFactory::createMiddleware`` method.
+
+Then you can reference and configure the
+``messenger.middleware.doctrine_transaction_middleware`` service as a middleware:
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        # config/packages/messenger.yaml
+        framework:
+            messenger:
+                buses:
+                    command_bus:
+                        middleware:
+                            # Using defaults:
+                            - doctrine_transaction_middleware
+                            # Using another entity manager:
+                            - doctrine_transaction_middleware: ['custom']
+
+    .. code-block:: xml
+
+        <!-- config/packages/messenger.xml -->
+        <container xmlns="http://symfony.com/schema/dic/symfony"
+            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+            xmlns:framework="http://symfony.com/schema/dic/symfony"
+            xsi:schemaLocation="http://symfony.com/schema/dic/services
+                http://symfony.com/schema/dic/services/services-1.0.xsd
+                http://symfony.com/schema/dic/symfony
+                http://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
+
+            <framework:config>
+                <framework:messenger>
+                    <framework:bus name="command_bus">
+                        <!-- Using defaults: -->
+                        <framework:middleware id="doctrine_transaction_middleware" />
+                        <!-- Using another entity manager -->
+                        <framework:middleware id="doctrine_transaction_middleware">
+                            <framework:argument>custom</framework:argument>
+                        </framework:middleware>
+                    </framework:bus>
+                </framework:messenger>
+            </framework:config>
+        </container>
+
+    .. code-block:: php
+
+        // config/packages/messenger.php
+        $container->loadFromExtension('framework', array(
+            'messenger' => array(
+                'buses' => array(
+                    'command_bus' => array(
+                        'middleware' => array(
+                            // Using defaults:
+                            'doctrine_transaction_middleware',
+                            // Using another entity manager
+                            array('id' => 'doctrine_transaction_middleware', 'arguments' => array('custom')),
+                        ),
+                    ),
+                ),
+            ),
+        ));
+
+.. note::
+
+    The ``doctrine_transaction_middleware`` shortcut is a convention. The real
+    service id is prefixed with the ``messenger.middleware.`` namespace.
+
+.. note::
+
+    Middleware factories only allow scalar and array arguments in config (no
+    references to other services). For most advanced use-cases, register a
+    concrete definition of the middleware manually and use its id.
+
+.. tip::
+
+    The ``doctrine_transaction_middleware`` is a built-in middleware wired
+    automatically when the DoctrineBundle and the Messenger component are
+    installed and enabled.
+
 Your own Transport
 ------------------
 

reference/constraints/NotBlank.rst

@@ -2,7 +2,7 @@ NotBlank
 ========
 
 Validates that a value is not blank - meaning not equal to a blank string,
-a blank array or ``null``::
+a blank array, ``null`` or ``false``::
 
     if (false === $value || (empty($value) && '0' != $value)) {
         // validation will fail

reference/forms/types/checkbox.rst

@@ -6,12 +6,16 @@ CheckboxType Field
 
 Creates a single input checkbox. This should always be used for a field
 that has a boolean value: if the box is checked, the field will be set to
-true, if the box is unchecked, the value will be set to false.
+true, if the box is unchecked, the value will be set to false. Optionally
+you can specify an array of values that, if submitted, will be evaluated
+to "false" as well (this differs from what HTTP defines, but can be handy
+if you want to handle submitted values like "0" or "false").
 
 +-------------+------------------------------------------------------------------------+
 | Rendered as | ``input`` ``checkbox`` field                                           |
 +-------------+------------------------------------------------------------------------+
-| Options     | - `value`_                                                             |
+| Options     | - `false_values`_                                                      |
+|             | - `value`_                                                             |
 +-------------+------------------------------------------------------------------------+
 | Overridden  | - `compound`_                                                          |
 | options     | - `empty_data`_                                                        |
@@ -48,6 +52,13 @@ Example Usage
 Field Options
 -------------
 
+false_values
+~~~~~~~~~~~~
+
+**type**: ``array`` **default**: ``array(null)``
+
+An array of values to be interpreted as ``false``.
+
 .. include:: /reference/forms/types/options/value.rst.inc
 
 Overridden Options

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

@@ -3,8 +3,9 @@ choice_attr
 
 **type**: ``array``, ``callable`` or ``string`` **default**: ``array()``
 
-Use this to add additional HTML attributes to each choice. This can be an array
-of attributes (if they are the same for each choice), a callable or a property path
+Use this to add additional HTML attributes to each choice. This can be
+an associative array where the keys match the choice keys and the values
+are the attributes for each choice, a callable or a property path
 (just like `choice_label`_).
 
 If an array, the keys of the ``choices`` array must be used as keys::