Merge branch '4.2'

* 4.2:
  Improved routing section
  minor tweak
  Apply suggestions from code review
  Encore (advanced): add documentation for `configureLoaderRule()` method

Author: HeahDude

components/routing.rst

@@ -39,8 +39,8 @@ your autoloader to load the Routing component::
 
     use Symfony\Component\Routing\Matcher\UrlMatcher;
     use Symfony\Component\Routing\RequestContext;
-    use Symfony\Component\Routing\RouteCollection;
     use Symfony\Component\Routing\Route;
+    use Symfony\Component\Routing\RouteCollection;
 
     $route = new Route('/foo', ['_controller' => 'MyController']);
     $routes = new RouteCollection();
@@ -82,20 +82,24 @@ be thrown.
 Defining Routes
 ~~~~~~~~~~~~~~~
 
-A full route definition can contain up to seven parts:
+A full route definition can contain up to eight parts:
 
-#. The URL path route. This is matched against the URL passed to the `RequestContext`,
-   and can contain named wildcard placeholders (e.g. ``{placeholders}``)
-   to match dynamic parts in the URL.
+#. The URL pattern. This is matched against the URL passed to the
+   ``RequestContext``. It is not a regular expression, but can contain named
+   wildcard placeholders (e.g. ``{slug}``) to match dynamic parts in the URL.
+   The component will create the regular expression from it.
 
-#. An array of default values. This contains an array of arbitrary values
-   that will be returned when the request matches the route.
+#. An array of default parameters. This contains an array of arbitrary values
+   that will be returned when the request matches the route. It is used by
+   convention to map a controller to the route.
 
 #. An array of requirements. These define constraints for the values of the
-   placeholders as regular expressions.
+   placeholders in the pattern as regular expressions.
 
-#. An array of options. These contain internal settings for the route and
-   are the least commonly needed.
+#. An array of options. These contain advanced settings for the route and
+   can be used to control encoding or customize compilation.
+   See :ref:`routing-unicode-support` below. You can learn more about them by
+   reading :method:`Symfony\\Component\\Routing\\Route::setOptions` implementation.
 
 #. A host. This is matched against the host of the request. See
    :doc:`/routing/hostname_pattern` for more details.
@@ -105,6 +109,10 @@ A full route definition can contain up to seven parts:
 #. An array of methods. These enforce a certain HTTP request method (``HEAD``,
    ``GET``, ``POST``, ...).
 
+#. A condition, using the :doc:`/components/expression_language/syntax`.
+   A string that must evaluate to ``true`` so the route matches. See
+   :doc:`/routing/conditions` for more details.
+
 Take the following route, which combines several of these ideas::
 
     $route = new Route(
@@ -114,7 +122,8 @@ Take the following route, which combines several of these ideas::
         [], // options
         '{subdomain}.example.com', // host
         [], // schemes
-        [] // methods
+        [], // methods
+        'context.getHost() matches "/(secure|admin).example.com/"' // condition
     );
 
     // ...
@@ -138,19 +147,22 @@ When using wildcards, these are returned in the array result when calling
 ``match``. The part of the path that the wildcard matched (e.g. ``2012-01``) is used
 as value.
 
-.. tip::
+A placeholder matches any character except slashes ``/`` by default, unless you define
+a specific requirement for it.
+The reason is that they are used by convention to separate different placeholders.
 
-    If you want to match all URLs which start with a certain path and end in an
-    arbitrary suffix you can use the following route definition::
+If you want a placeholder to match anything, it must be the last of the route::
 
-        $route = new Route(
-            '/start/{suffix}',
-            ['suffix' => ''],
-            ['suffix' => '.*']
-        );
+    $route = new Route(
+        '/start/{required}/{anything}',
+        ['required' => 'default'], // should always be defined
+        ['anything' => '.*'] // explicit requirement to allow "/"
+    );
 
-Using Prefixes
-~~~~~~~~~~~~~~
+Learn more about it by reading :ref:`routing/slash_in_parameter`.
+
+Using Prefixes and Collection Settings
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 You can add routes or other instances of
 :class:`Symfony\\Component\\Routing\\RouteCollection` to *another* collection.
@@ -166,11 +178,12 @@ host to all routes of a subtree using methods provided by the
     $subCollection->add(...);
     $subCollection->addPrefix('/prefix');
     $subCollection->addDefaults([...]);
-    $subCollection->addRequirements([]);
-    $subCollection->addOptions([]);
-    $subCollection->setHost('admin.example.com');
+    $subCollection->addRequirements([...]);
+    $subCollection->addOptions([...]);
+    $subCollection->setHost('{subdomain}.example.com');
     $subCollection->setMethods(['POST']);
     $subCollection->setSchemes(['https']);
+    $subCollection->setCondition('context.getHost() matches "/(secure|admin).example.com/"');
 
     $rootCollection->addCollection($subCollection);
 
@@ -210,7 +223,7 @@ Generate a URL
 
 While the :class:`Symfony\\Component\\Routing\\Matcher\\UrlMatcher` tries
 to find a route that fits the given request you can also build a URL from
-a certain route::
+a certain route with the :class:`Symfony\\Component\\Routing\\Generator\\UrlGenerator`::
 
     use Symfony\Component\Routing\Generator\UrlGenerator;
     use Symfony\Component\Routing\RequestContext;
@@ -372,14 +385,17 @@ automatically in the background if you want to use it. A basic example of the
         ['cache_dir' => __DIR__.'/cache'],
         $requestContext
     );
-    $router->match('/foo/bar');
+    $parameters = $router->match('/foo/bar');
+    $url = $router->generate('some_route', ['parameter' => 'value']);
 
 .. note::
 
     If you use caching, the Routing component will compile new classes which
     are saved in the ``cache_dir``. This means your script must have write
     permissions for that location.
 
+.. _routing-unicode-support:
+
 Unicode Routing Support
 ~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -514,7 +530,7 @@ You can also include UTF-8 strings as routing requirements:
              * @Route(
              *     "/category/{name}",
              *     name="route2",
-             *     defaults={"name"="한국어"},
+             *     defaults={"name": "한국어"},
              *     utf8=true
              * )
              */

frontend/encore/advanced-config.rst

@@ -170,6 +170,47 @@ normally use from the command-line interface:
         keepPublicPath: true,
     });
 
+Having the full control on Loaders Rules
+----------------------------------------
+
+The method ``configureLoaderRule()`` provides a clean way to configure Webpack loaders rules (``module.rules``, see `Configuration <https://webpack.js.org/concepts/loaders/#configuration>`_).
+
+This is a low-level method. All your modifications will be applied just before pushing the loaders rules to Webpack.
+It means that you can override the default configuration provided by Encore, which may break things. Be careful when using it.
+
+One use might be to configure the ``eslint-loader`` to lint Vue files too.
+The following code is equivalent:
+
+.. code-block:: javascript
+
+    // Manually
+    const webpackConfig = Encore.getWebpackConfig();
+
+    const eslintLoader = webpackConfig.module.rules.find(rule => rule.loader === 'eslint-loader');
+    eslintLoader.test = /\.(jsx?|vue)$/;
+
+    return webpackConfig;
+
+    // Using Encore.configureLoaderRule()
+    Encore.configureLoaderRule('eslint', loaderRule => {
+        loaderRule.test = /\.(jsx?|vue)$/
+    });
+
+    return Encore.getWebpackConfig();
+
+The following loaders are configurable with ``configureLoaderRule()``:
+  - ``javascript`` (alias ``js``)
+  - ``css``
+  - ``images``
+  - ``fonts``
+  - ``sass`` (alias ``scss``)
+  - ``less``
+  - ``stylus``
+  - ``vue``
+  - ``eslint``
+  - ``typescript`` (alias ``ts``)
+  - ``handlebars``
+
 .. _`configuration options`: https://webpack.js.org/configuration/
 .. _`Webpack's watchOptions`: https://webpack.js.org/configuration/watch/#watchoptions
 .. _`array of configurations`: https://github.com/webpack/docs/wiki/configuration#multiple-configurations

routing.rst

@@ -4,13 +4,14 @@
 Routing
 =======
 
-Beautiful URLs are a must for any serious web application. This means leaving behind
-ugly URLs like ``index.php?article_id=57`` in favor of something like ``/read/intro-to-symfony``.
+Beautiful URLs are a must for any serious web application. This means leaving
+behind ugly URLs like ``index.php?article_id=57`` in favor of something like
+``/read/intro-to-symfony``.
 
 Having flexibility is even more important. What if you need to change the
 URL of a page from ``/blog`` to ``/news``? How many links would you need to
 hunt down and update to make the change? If you're using Symfony's router,
-the change is simple.
+the change should be trivial.
 
 .. index::
    single: Routing; Basics
@@ -20,19 +21,13 @@ the change is simple.
 Creating Routes
 ---------------
 
-A *route* is a map from a URL path to a controller. Suppose you want one route that
-matches ``/blog`` exactly and another more dynamic route that can match *any* URL
-like ``/blog/my-post`` or ``/blog/all-about-symfony``.
+A *route* is a map from a URL path to attributes (i.e a controller). Suppose
+you want one route that matches ``/blog`` exactly and another more dynamic
+route that can match *any* URL like ``/blog/my-post`` or
+``/blog/all-about-symfony``.
 
-Routes can be configured in YAML, XML and PHP. All formats provide the same
-features and performance, so choose the one you prefer. If you choose PHP
-annotations, run this command once in your app to add support for them:
-
-.. code-block:: terminal
-
-    $ composer require annotations
-
-Now you can configure the routes:
+Routes can be configured in YAML, XML, PHP or annotations. All formats provide
+the same features and performance, so choose the one you prefer:
 
 .. configuration-block::
 
@@ -58,6 +53,7 @@ Now you can configure the routes:
 
             /**
              * Matches /blog/*
+             * but not /blog/slug/extra-part
              *
              * @Route("/blog/{slug}", name="blog_show")
              */
@@ -74,10 +70,13 @@ Now you can configure the routes:
 
         # config/routes.yaml
         blog_list:
+            # Matches /blog exactly
             path:     /blog
             controller: App\Controller\BlogController::list
 
         blog_show:
+            # Matches /blog/*
+            # but not /blog/slug/extra-part
             path:     /blog/{slug}
             controller: App\Controller\BlogController::show
 
@@ -90,10 +89,13 @@ Now you can configure the routes:
             xsi:schemaLocation="http://symfony.com/schema/routing
                 https://symfony.com/schema/routing/routing-1.0.xsd">
 
+            <!-- Matches /blog exactly -->
             <route id="blog_list" path="/blog" controller="App\Controller\BlogController::list">
                 <!-- settings -->
             </route>
 
+            <!-- Matches /blog/* -->
+            <!-- but not /blog/slug/extra-part -->
             <route id="blog_show" path="/blog/{slug}" controller="App\Controller\BlogController::show">
                 <!-- settings -->
             </route>
@@ -107,9 +109,12 @@ Now you can configure the routes:
         use App\Controller\BlogController;
 
         return function (RoutingConfigurator $routes) {
+            // Matches /blog exactly
             $routes->add('blog_list', '/blog')
                 ->controller([BlogController::class, 'list'])
             ;
+            // Matches /blog/*
+            // but not /blog/slug/extra-part
             $routes->add('blog_show', '/blog/{slug}')
                 ->controller([BlogController::class, 'show'])
             ;
@@ -121,13 +126,21 @@ Thanks to these two routes:
   is executed;
 
 * If the user goes to ``/blog/*``, the second route is matched and ``show()``
-  is executed. Because the route path is ``/blog/{slug}``, a ``$slug`` variable is
-  passed to ``show()`` matching that value. For example, if the user goes to
+  is executed. Because the route path is ``/blog/{slug}``, a ``$slug`` variable
+  is passed to ``show()`` matching that value. For example, if the user goes to
   ``/blog/yay-routing``, then ``$slug`` will equal ``yay-routing``.
 
-Whenever you have a ``{placeholder}`` in your route path, that portion becomes a
-wildcard: it matches *any* value. Your controller can now *also* have an argument
-called ``$placeholder`` (the wildcard and argument names *must* match).
+Whenever you have a ``{placeholder}`` in your route path, that portion becomes
+a wildcard: it matches *any* value. Your controller can now *also* have an
+argument called ``$placeholder`` (the wildcard and argument names *must*
+match).
+
+.. caution::
+
+    However the slash ``/`` is ignored by default in placeholder values because
+    the router uses it as separator between different placeholders.
+    To learn more about this, you can read
+    :ref:`routing/slash_in_parameter`.
 
 Each route also has an internal name: ``blog_list`` and ``blog_show``. These can
 be anything (as long as each is unique) and don't have any meaning yet. You'll
@@ -1035,6 +1048,3 @@ Learn more about Routing
     :glob:
 
     routing/*
-
-.. _`JMSI18nRoutingBundle`: https://github.com/schmittjoh/JMSI18nRoutingBundle
-.. _`BeSimpleI18nRoutingBundle`: https://github.com/BeSimple/BeSimpleI18nRoutingBundle

routing/conditions.rst

@@ -6,7 +6,7 @@ How to Restrict Route Matching through Conditions
 
 A route can be made to match only certain routing placeholders (via regular
 expressions), HTTP methods, or host names. If you need more flexibility to
-define arbitrary matching logic, use the ``conditions`` routing option:
+define arbitrary matching logic, use the ``condition`` routing setting:
 
 .. configuration-block::
 

routing/custom_route_loader.rst

@@ -122,11 +122,17 @@ and configure the service and method to call:
             $routes->import('admin_route_loader:loadRoutes', 'service');
         };
 
-In this example, the routes are loaded by calling the ``loadRoutes()`` method of
-the service whose ID is ``admin_route_loader``. Your service doesn't have to
+In this example, the routes are loaded by calling the ``loadRoutes()`` method
+of the service whose ID is ``admin_route_loader``. Your service doesn't have to
 extend or implement any special class, but the called method must return a
 :class:`Symfony\\Component\\Routing\\RouteCollection` object.
 
+.. note::
+
+    The routes defined using service route loaders will be automatically
+    cached by the framework. So whenever your service should load new routes,
+    don't forget to clear the cache.
+
 Creating a custom Loader
 ------------------------
 
@@ -240,8 +246,7 @@ Now define a service for the ``ExtraLoader``:
         // config/services.php
         use App\Routing\ExtraLoader;
 
-        $container
-            ->autowire(ExtraLoader::class)
+        $container->autowire(ExtraLoader::class)
             ->addTag('routing.loader')
         ;
 
@@ -250,7 +255,7 @@ as potential route loaders and added as specialized route loaders to the
 ``routing.loader`` *service*, which is an instance of
 :class:`Symfony\\Bundle\\FrameworkBundle\\Routing\\DelegatingLoader`.
 
-Using the custom Loader
+Using the Custom Loader
 ~~~~~~~~~~~~~~~~~~~~~~~
 
 If you did nothing else, your custom routing loader would *not* be called.
@@ -297,7 +302,7 @@ for the ``ExtraLoader``, so it is set to ``.`` (a single dot).
     cached by the framework. So whenever you change something in the loader
     class itself, don't forget to clear the cache.
 
-More advanced Loaders
+More Advanced Loaders
 ---------------------
 
 If your custom route loader extends from