Merge branch '3.4' into 4.0

* 3.4:
  Made the testing form examples consistent
  Updated latest maintained version in documentation overview
  Remove unused var - custom auth provider example
  Use '[]' notation, add missing "()" update class name
  Fixed the params in ChoiceType methods
  Documented the logout_on_user_change option
  Explain how to check if a route exists
  Better explain the use of multiple roles in access_control
  Added notes in the components doc to point to the main Symfony articles
  Added a small note about Webpack server and Symfony server
  Don't recommend base64 encoding of random_bytes result
  Added a missing validator example
  Minor tweak about enalbing the profiler in the tests
  Clarification on search user

components/browser_kit.rst

@@ -28,6 +28,12 @@ Alternatively, you can clone the `<https://github.com/symfony/browser-kit>`_ rep
 Basic Usage
 -----------
 
+.. seealso::
+
+    This article explains how to use the BrowserKit features as an independent
+    component in any PHP application. Read the :ref:`Symfony Functional Tests <functional-tests>`
+    article to learn about how to use it in Symfony applications.
+
 Creating a Client
 ~~~~~~~~~~~~~~~~~
 

components/console.rst

@@ -26,6 +26,12 @@ Alternatively, you can clone the `<https://github.com/symfony/console>`_ reposit
 Creating a Console Application
 ------------------------------
 
+.. seealso::
+
+    This article explains how to use the Console features as an independent
+    component in any PHP application. Read the :doc:`/console` article to
+    learn about how to use it in Symfony applications.
+
 First, you need to create a PHP script to define the console application::
 
     #!/usr/bin/env php

components/css_selector.rst

@@ -21,6 +21,12 @@ Alternatively, you can clone the `<https://github.com/symfony/css-selector>`_ re
 Usage
 -----
 
+.. seealso::
+
+    This article explains how to use the CssSelector features as an independent
+    component in any PHP application. Read the :ref:`Symfony Functional Tests <functional-tests>`
+    article to learn about how to use it when creating Symfony tests.
+
 Why to Use CSS selectors?
 ~~~~~~~~~~~~~~~~~~~~~~~~~
 

components/dependency_injection.rst

@@ -26,6 +26,12 @@ Alternatively, you can clone the `<https://github.com/symfony/dependency-injecti
 Basic Usage
 -----------
 
+.. seealso::
+
+    This article explains how to use the DependencyInjection features as an
+    independent component in any PHP application. Read the :doc:`/service_container`
+    article to learn about how to use it in Symfony applications.
+
 You might have a simple class like the following ``Mailer`` that
 you want to make available as a service::
 

components/dom_crawler.rst

@@ -26,6 +26,12 @@ Alternatively, you can clone the `<https://github.com/symfony/dom-crawler>`_ rep
 Usage
 -----
 
+.. seealso::
+
+    This article explains how to use the DomCrawler features as an independent
+    component in any PHP application. Read the :ref:`Symfony Functional Tests <functional-tests>`
+    article to learn about how to use it when creating Symfony tests.
+
 The :class:`Symfony\\Component\\DomCrawler\\Crawler` class provides methods
 to query and manipulate HTML and XML documents.
 

components/event_dispatcher.rst

@@ -63,6 +63,12 @@ Alternatively, you can clone the `<https://github.com/symfony/event-dispatcher>`
 Usage
 -----
 
+.. seealso::
+
+    This article explains how to use the EventDispatcher features as an
+    independent component in any PHP application. Read the :doc:`/event_dispatcher`
+    article to learn about how to use it in Symfony applications.
+
 Events
 ~~~~~~
 

components/form.rst

@@ -27,10 +27,11 @@ Alternatively, you can clone the `<https://github.com/symfony/form>`_ repository
 Configuration
 -------------
 
-.. tip::
+.. seealso::
 
-    If you are working with the full-stack Symfony Framework, the Form component
-    is already configured for you. In this case, skip to :ref:`component-form-intro-create-simple-form`.
+    This article explains how to use the Form features as an independent
+    component in any PHP application. Read the :doc:`/forms` article to learn
+    about how to use it in Symfony applications.
 
 In Symfony, forms are represented by objects and these objects are built
 by using a *form factory*. Building a form factory is simple::

components/http_foundation.rst

@@ -27,6 +27,13 @@ Alternatively, you can clone the `<https://github.com/symfony/http-foundation>`_
 
 .. include:: /components/require_autoload.rst.inc
 
+.. seealso::
+
+    This article explains how to use the HttpFoundation features as an
+    independent component in any PHP application. In Symfony applications
+    everything is already configured and ready to use. Read the :doc:`/controller`
+    article to learn about how to use these features when creating controllers.
+
 .. _component-http-foundation-request:
 
 Request

components/http_kernel.rst

@@ -25,6 +25,15 @@ Alternatively, you can clone the `<https://github.com/symfony/http-kernel>`_ rep
 The Workflow of a Request
 -------------------------
 
+.. seealso::
+
+    This article explains how to use the HttpKernel features as an independent
+    component in any PHP application. In Symfony applications everything is
+    already configured and ready to use. Read the :doc:`/controller` and
+    :doc:`/event_dispatcher` articles to learn about how to use it to create
+    controllers and define events in Symfony applications.
+
+
 Every HTTP web interaction begins with a request and ends with a response.
 Your job as a developer is to create PHP code that reads the request information
 (e.g. the URL) and creates and returns a response (e.g. an HTML page or JSON string).

components/intl.rst

@@ -13,6 +13,12 @@ The Intl Component
     The replacement layer is limited to the locale "en". If you want to use
     other locales, you should `install the intl extension`_ instead.
 
+.. seealso::
+
+    This article explains how to use the Intl features as an independent component
+    in any PHP application. Read the :doc:`/translation` article to learn about
+    how to internationalize and manage the user locale in Symfony applications.
+
 Installation
 ------------
 

components/phpunit_bridge.rst

@@ -62,6 +62,12 @@ to register a new `test listener`_ called ``SymfonyTestsListener``:
 Usage
 -----
 
+.. seealso::
+
+    This article explains how to use the PhpUnitBridge features as an independent
+    component in any PHP application. Read the :doc:`/testing` article to learn
+    about how to use it in Symfony applications.
+
 Once the component is installed, a ``simple-phpunit`` script is created in the
 ``vendor/`` directory to run tests. This script wraps the original PHPUnit binary
 to provide more features:

components/routing.rst

@@ -22,6 +22,12 @@ Alternatively, you can clone the `<https://github.com/symfony/routing>`_ reposit
 Usage
 -----
 
+.. seealso::
+
+    This article explains how to use the Routing features as an independent
+    component in any PHP application. Read the :doc:`/routing` article to learn
+    about how to use it in Symfony applications.
+
 In order to set up a basic routing system you need three parts:
 
 * A :class:`Symfony\\Component\\Routing\\RouteCollection`, which contains the route definitions (instances of the class :class:`Symfony\\Component\\Routing\\Route`)
@@ -229,6 +235,28 @@ a certain route::
     of the current :class:`Symfony\\Component\\Routing\\RequestContext` does
     not match the requirement.
 
+Check if a Route Exists
+~~~~~~~~~~~~~~~~~~~~~~~
+
+In highly dynamic applications, it may be necessary to check whether a route
+exists before using it to generate a URL. In those cases, don't use the
+:method:`Symfony\\Component\\Routing\\Router::getRouteCollection` method because
+that regenerates the routing cache and slows down the application.
+
+Instead, try to generate the URL and catch the
+:class:`Symfony\\Component\\Routing\\Exception\\RouteNotFoundException` thrown
+when the route doesn't exist::
+
+    use Symfony\Component\Routing\Exception\RouteNotFoundException;
+
+    // ...
+
+    try {
+        $url = $generator->generate($dynamicRouteName, $parameters);
+    } catch (RouteNotFoundException $e) {
+        // the route is not defined...
+    }
+
 Load Routes from a File
 ~~~~~~~~~~~~~~~~~~~~~~~
 

components/security.rst

@@ -39,6 +39,12 @@ used separately:
 ``symfony/security-acl``
     It provides a fine grained permissions mechanism based on Access Control Lists.
 
+.. seealso::
+
+    This article explains how to use the Security features as an independent
+    component in any PHP application. Read the :doc:`/security` article to learn
+    about how to use it in Symfony applications.
+
 Learn More
 ----------
 

components/security/secure_tools.rst

@@ -41,9 +41,8 @@ the number bytes passed as an argument (10 in the above example).
     The ``random_bytes()`` function returns a binary string which may contain
     the ``\0`` character. This can cause trouble in several common scenarios,
     such as storing this value in a database or including it as part of the
-    URL. The solution is to encode or hash the value returned by
-    ``random_bytes()`` (to do that, you can use a simple ``base64_encode()``
-    PHP function).
+    URL. The solution is to hash the value returned by ``random_bytes()`` with
+    a hashing function such as :phpfunction:`md5` or :phpfunction:`sha1`.
 
 Generating a Secure Random Number
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

components/serializer.rst

@@ -38,6 +38,12 @@ must also be installed.
 Usage
 -----
 
+.. seealso::
+
+    This article explains how to use the Serializer features as an independent
+    component in any PHP application. Read the :doc:`/serializer` article to
+    learn about how to use it in Symfony applications.
+
 Using the Serializer component is really simple. You just need to set up
 the :class:`Symfony\\Component\\Serializer\\Serializer` specifying
 which encoders and normalizer are going to be available::

components/templating.rst

@@ -27,6 +27,12 @@ Alternatively, you can clone the `<https://github.com/symfony/templating>`_ repo
 Usage
 -----
 
+.. seealso::
+
+    This article explains how to use the Templating features as an independent
+    component in any PHP application. Read the :doc:`/templating` article to
+    learn about how to work with templates in Symfony applications.
+
 The :class:`Symfony\\Component\\Templating\\PhpEngine` class is the entry point
 of the component. It needs a
 template name parser (:class:`Symfony\\Component\\Templating\\TemplateNameParserInterface`)

components/translation.rst

@@ -19,6 +19,13 @@ Alternatively, you can clone the `<https://github.com/symfony/translation>`_ rep
 
 .. include:: /components/require_autoload.rst.inc
 
+.. seealso::
+
+    This article explains how to use the Translation features as an independent
+    component in any PHP application. Read the :doc:`/translation` article to
+    learn about how to internationalize and manage the user locale in Symfony
+    applications.
+
 Constructing the Translator
 ---------------------------
 

components/validator.rst

@@ -22,6 +22,12 @@ Alternatively, you can clone the `<https://github.com/symfony/validator>`_ repos
 Usage
 -----
 
+.. seealso::
+
+    This article explains how to use the Validator features as an independent
+    component in any PHP application. Read the :doc:`/validation` article to
+    learn about how to validate data and entities in Symfony applications.
+
 The Validator component behavior is based on two concepts:
 
 * Constraints, which define the rules to be validated;

components/validator/metadata.rst

@@ -70,3 +70,28 @@ Classes
 Some constraints allow to validate the entire object. For example, the
 :doc:`Callback </reference/constraints/Callback>` constraint is a generic
 constraint that's applied to the class itself.
+
+Suppose that the class defines a ``validate()`` method to hold its custom
+validation logic::
+
+        // ...
+        use Symfony\Component\Validator\Context\ExecutionContextInterface;
+
+        public function validate(ExecutionContextInterface $context)
+        {
+            // ...
+        }
+
+Then, add the Validator component configuration to the class::
+
+    // ...
+    use Symfony\Component\Validator\Mapping\ClassMetadata;
+    use Symfony\Component\Validator\Constraints as Assert;
+
+    class Author
+    {
+        public static function loadValidatorMetadata(ClassMetadata $metadata)
+        {
+            $metadata->addConstraint(new Assert\Callback('validate'));
+        }
+    }

contributing/documentation/overview.rst

@@ -112,14 +112,14 @@ memorable name for the new branch (if you are fixing a reported issue, use
 
 .. code-block:: terminal
 
-    $ git checkout -b improve_install_article upstream/2.7
+    $ git checkout -b improve_install_article upstream/2.8
 
 In this example, the name of the branch is ``improve_install_article`` and the
-``upstream/2.7`` value tells Git to create this branch based on the ``2.7``
+``upstream/2.8`` value tells Git to create this branch based on the ``2.8``
 branch of the ``upstream`` remote, which is the original Symfony Docs repository.
 
 Fixes should always be based on the **oldest maintained branch** which contains
-the error. Nowadays this is the ``2.7`` branch. If you are instead documenting a
+the error. Nowadays this is the ``2.8`` branch. If you are instead documenting a
 new feature, switch to the first Symfony version that included it, e.g.
 ``upstream/3.1``. Not sure? That's ok! Just use the ``upstream/master`` branch.
 
@@ -155,7 +155,7 @@ changes should be applied:
    :align: center
 
 In this example, the **base fork** should be ``symfony/symfony-docs`` and
-the **base** branch should be the ``2.7``, which is the branch that you selected
+the **base** branch should be the ``2.8``, which is the branch that you selected
 to base your changes on. The **head fork** should be your forked copy
 of ``symfony-docs`` and the **compare** branch should be ``improve_install_article``,
 which is the name of the branch you created and where you made your changes.
@@ -205,7 +205,7 @@ contribution to the Symfony docs:
     # create a new branch based on the oldest maintained version
     $ cd projects/symfony-docs/
     $ git fetch upstream
-    $ git checkout -b my_changes upstream/2.7
+    $ git checkout -b my_changes upstream/2.8
 
     # ... do your changes
 
@@ -288,8 +288,8 @@ into multiple branches, corresponding to the different versions of Symfony itsel
 The ``master`` branch holds the documentation for the development branch of
 the code.
 
-Unless you're documenting a feature that was introduced after Symfony 2.7,
-your changes should always be based on the ``2.7`` branch. Documentation managers
+Unless you're documenting a feature that was introduced after Symfony 2.8,
+your changes should always be based on the ``2.8`` branch. Documentation managers
 will use the necessary Git-magic to also apply your changes to all the active
 branches of the documentation.
 

frontend/encore/dev-server.rst

@@ -24,6 +24,12 @@ by the normal `webpack-dev-server`_. For example:
 
 This will start a server at ``https://localhost:9000``.
 
+.. note::
+
+    This Webpack server is independent from
+    :doc:`Symfony's development web server </setup/built_in_web_server>` and
+    you need to run both separately.
+
 Using dev-server inside a VM
 ----------------------------
 

reference/configuration/security.rst

@@ -123,6 +123,7 @@ Each part will be explained in the next section.
                     # See "Firewall Context" below for more details
                     context: context_key
                     stateless: false
+                    logout_on_user_change: false
                     x509:
                         provider: some_key_from_above
                     remote_user:
@@ -430,6 +431,24 @@ The ``invalidate_session`` option allows to redefine this behavior. Set this
 option to ``false`` in every firewall and the user will only be logged out from
 the current firewall and not the other ones.
 
+logout_on_user_change
+~~~~~~~~~~~~~~~~~~~~~
+
+**type**: ``boolean`` **default**: ``false``
+
+.. versionadded:: 3.4
+    The ``logout_on_user_change`` option was introduced in Symfony 3.4.
+
+If ``true`` this option makes Symfony to trigger a logout when the user has
+changed. Not doing that is deprecated, so this option should be set to ``true``
+to avoid getting deprecation messages.
+
+The user is considered to have changed when the user class implements
+:class:`Symfony\\Component\\Security\\Core\\User\\EquatableInterface` and the
+``isEqualTo()`` method returns ``false``. Also, when any of the properties
+required by the :class:`Symfony\\Component\\Security\\Core\\User\\UserInterface`
+(like the username, password or salt) changes.
+
 .. _reference-security-ldap:
 
 LDAP functionality