Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Commit c0a0a68

Browse files
HeahDudeHeahDude
committed
Merge branch '3.4' into 4.2
* 3.4: Improved routing section minor tweak Apply suggestions from code review Encore (advanced): add documentation for `configureLoaderRule()` method
2 parents 667953e + 735ef0a commit c0a0a68

14 files changed

+201
-82
lines changed

‎components/routing.rst

Lines changed: 43 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -39,8 +39,8 @@ your autoloader to load the Routing component::
3939

4040
use Symfony\Component\Routing\Matcher\UrlMatcher;
4141
use Symfony\Component\Routing\RequestContext;
42-
use Symfony\Component\Routing\RouteCollection;
4342
use Symfony\Component\Routing\Route;
43+
use Symfony\Component\Routing\RouteCollection;
4444

4545
$route = new Route('/foo', ['_controller' => 'MyController']);
4646
$routes = new RouteCollection();
@@ -82,20 +82,24 @@ be thrown.
8282
Defining Routes
8383
~~~~~~~~~~~~~~~
8484

85-
A full route definition can contain up to seven parts:
85+
A full route definition can contain up to eight parts:
8686

87-
#. The URL path route. This is matched against the URL passed to the `RequestContext`,
88-
and can contain named wildcard placeholders (e.g. ``{placeholders}``)
89-
to match dynamic parts in the URL.
87+
#. The URL pattern. This is matched against the URL passed to the
88+
``RequestContext``. It is not a regular expression, but can contain named
89+
wildcard placeholders (e.g. ``{slug}``) to match dynamic parts in the URL.
90+
The component will create the regular expression from it.
9091

91-
#. An array of default values. This contains an array of arbitrary values
92-
that will be returned when the request matches the route.
92+
#. An array of default parameters. This contains an array of arbitrary values
93+
that will be returned when the request matches the route. It is used by
94+
convention to map a controller to the route.
9395

9496
#. An array of requirements. These define constraints for the values of the
95-
placeholders as regular expressions.
97+
placeholders in the pattern as regular expressions.
9698

97-
#. An array of options. These contain internal settings for the route and
98-
are the least commonly needed.
99+
#. An array of options. These contain advanced settings for the route and
100+
can be used to control encoding or customize compilation.
101+
See :ref:`routing-unicode-support` below. You can learn more about them by
102+
reading :method:`Symfony\\Component\\Routing\\Route::setOptions` implementation.
99103

100104
#. A host. This is matched against the host of the request. See
101105
:doc:`/routing/hostname_pattern` for more details.
@@ -105,6 +109,10 @@ A full route definition can contain up to seven parts:
105109
#. An array of methods. These enforce a certain HTTP request method (``HEAD``,
106110
``GET``, ``POST``, ...).
107111

112+
#. A condition, using the :doc:`/components/expression_language/syntax`.
113+
A string that must evaluate to ``true`` so the route matches. See
114+
:doc:`/routing/conditions` for more details.
115+
108116
Take the following route, which combines several of these ideas::
109117

110118
$route = new Route(
@@ -114,7 +122,8 @@ Take the following route, which combines several of these ideas::
114122
[], // options
115123
'{subdomain}.example.com', // host
116124
[], // schemes
117-
[] // methods
125+
[], // methods
126+
'context.getHost() matches "/(secure|admin).example.com/"' // condition
118127
);
119128

120129
// ...
@@ -138,19 +147,22 @@ When using wildcards, these are returned in the array result when calling
138147
``match``. The part of the path that the wildcard matched (e.g. ``2012-01``) is used
139148
as value.
140149

141-
.. tip::
150+
A placeholder matches any character except slashes ``/`` by default, unless you define
151+
a specific requirement for it.
152+
The reason is that they are used by convention to separate different placeholders.
142153

143-
If you want to match all URLs which start with a certain path and end in an
144-
arbitrary suffix you can use the following route definition::
154+
If you want a placeholder to match anything, it must be the last of the route::
145155

146-
$route = new Route(
147-
'/start/{suffix}',
148-
['suffix' => ''],
149-
['suffix' => '.*']
150-
);
156+
$route = new Route(
157+
'/start/{required}/{anything}',
158+
['required' => 'default'], // should always be defined
159+
['anything' => '.*'] // explicit requirement to allow "/"
160+
);
151161

152-
Using Prefixes
153-
~~~~~~~~~~~~~~
162+
Learn more about it by reading :ref:`routing/slash_in_parameter`.
163+
164+
Using Prefixes and Collection Settings
165+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
154166

155167
You can add routes or other instances of
156168
:class:`Symfony\\Component\\Routing\\RouteCollection` to *another* collection.
@@ -166,11 +178,12 @@ host to all routes of a subtree using methods provided by the
166178
$subCollection->add(...);
167179
$subCollection->addPrefix('/prefix');
168180
$subCollection->addDefaults([...]);
169-
$subCollection->addRequirements([]);
170-
$subCollection->addOptions([]);
171-
$subCollection->setHost('admin.example.com');
181+
$subCollection->addRequirements([...]);
182+
$subCollection->addOptions([...]);
183+
$subCollection->setHost('{subdomain}.example.com');
172184
$subCollection->setMethods(['POST']);
173185
$subCollection->setSchemes(['https']);
186+
$subCollection->setCondition('context.getHost() matches "/(secure|admin).example.com/"');
174187

175188
$rootCollection->addCollection($subCollection);
176189

@@ -210,7 +223,7 @@ Generate a URL
210223

211224
While the :class:`Symfony\\Component\\Routing\\Matcher\\UrlMatcher` tries
212225
to find a route that fits the given request you can also build a URL from
213-
a certain route::
226+
a certain route with the :class:`Symfony\\Component\\Routing\\Generator\\UrlGenerator`::
214227

215228
use Symfony\Component\Routing\Generator\UrlGenerator;
216229
use Symfony\Component\Routing\RequestContext;
@@ -372,14 +385,17 @@ automatically in the background if you want to use it. A basic example of the
372385
['cache_dir' => __DIR__.'/cache'],
373386
$requestContext
374387
);
375-
$router->match('/foo/bar');
388+
$parameters = $router->match('/foo/bar');
389+
$url = $router->generate('some_route', ['parameter' => 'value']);
376390

377391
.. note::
378392

379393
If you use caching, the Routing component will compile new classes which
380394
are saved in the ``cache_dir``. This means your script must have write
381395
permissions for that location.
382396

397+
.. _routing-unicode-support:
398+
383399
Unicode Routing Support
384400
~~~~~~~~~~~~~~~~~~~~~~~
385401

@@ -466,7 +482,7 @@ You can also include UTF-8 strings as routing requirements:
466482
* @Route(
467483
* "/category/{name}",
468484
* name="route2",
469-
* defaults={"name"="한국어"},
485+
* defaults={"name": "한국어"},
470486
* options={"utf8": true}
471487
* )
472488
*/

‎frontend/encore/advanced-config.rst

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -170,6 +170,47 @@ normally use from the command-line interface:
170170
keepPublicPath: true,
171171
});
172172
173+
Having the full control on Loaders Rules
174+
----------------------------------------
175+
176+
The method ``configureLoaderRule()`` provides a clean way to configure Webpack loaders rules (``module.rules``, see `Configuration <https://webpack.js.org/concepts/loaders/#configuration>`_).
177+
178+
This is a low-level method. All your modifications will be applied just before pushing the loaders rules to Webpack.
179+
It means that you can override the default configuration provided by Encore, which may break things. Be careful when using it.
180+
181+
One use might be to configure the ``eslint-loader`` to lint Vue files too.
182+
The following code is equivalent:
183+
184+
.. code-block:: javascript
185+
186+
// Manually
187+
const webpackConfig = Encore.getWebpackConfig();
188+
189+
const eslintLoader = webpackConfig.module.rules.find(rule => rule.loader === 'eslint-loader');
190+
eslintLoader.test = /\.(jsx?|vue)$/;
191+
192+
return webpackConfig;
193+
194+
// Using Encore.configureLoaderRule()
195+
Encore.configureLoaderRule('eslint', loaderRule => {
196+
loaderRule.test = /\.(jsx?|vue)$/
197+
});
198+
199+
return Encore.getWebpackConfig();
200+
201+
The following loaders are configurable with ``configureLoaderRule()``:
202+
- ``javascript`` (alias ``js``)
203+
- ``css``
204+
- ``images``
205+
- ``fonts``
206+
- ``sass`` (alias ``scss``)
207+
- ``less``
208+
- ``stylus``
209+
- ``vue``
210+
- ``eslint``
211+
- ``typescript`` (alias ``ts``)
212+
- ``handlebars``
213+
173214
.. _`configuration options`: https://webpack.js.org/configuration/
174215
.. _`Webpack's watchOptions`: https://webpack.js.org/configuration/watch/#watchoptions
175216
.. _`array of configurations`: https://github.com/webpack/docs/wiki/configuration#multiple-configurations

‎routing.rst

Lines changed: 33 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -4,13 +4,14 @@
44
Routing
55
=======
66

7-
Beautiful URLs are a must for any serious web application. This means leaving behind
8-
ugly URLs like ``index.php?article_id=57`` in favor of something like ``/read/intro-to-symfony``.
7+
Beautiful URLs are a must for any serious web application. This means leaving
8+
behind ugly URLs like ``index.php?article_id=57`` in favor of something like
9+
``/read/intro-to-symfony``.
910

1011
Having flexibility is even more important. What if you need to change the
1112
URL of a page from ``/blog`` to ``/news``? How many links would you need to
1213
hunt down and update to make the change? If you're using Symfony's router,
13-
the change is simple.
14+
the change should be trivial.
1415

1516
.. index::
1617
single: Routing; Basics
@@ -20,19 +21,13 @@ the change is simple.
2021
Creating Routes
2122
---------------
2223

23-
A *route* is a map from a URL path to a controller. Suppose you want one route that
24-
matches ``/blog`` exactly and another more dynamic route that can match *any* URL
25-
like ``/blog/my-post`` or ``/blog/all-about-symfony``.
24+
A *route* is a map from a URL path to attributes (i.e a controller). Suppose
25+
you want one route that matches ``/blog`` exactly and another more dynamic
26+
route that can match *any* URL like ``/blog/my-post`` or
27+
``/blog/all-about-symfony``.
2628

27-
Routes can be configured in YAML, XML and PHP. All formats provide the same
28-
features and performance, so choose the one you prefer. If you choose PHP
29-
annotations, run this command once in your app to add support for them:
30-
31-
.. code-block:: terminal
32-
33-
$ composer require annotations
34-
35-
Now you can configure the routes:
29+
Routes can be configured in YAML, XML, PHP or annotations. All formats provide
30+
the same features and performance, so choose the one you prefer:
3631

3732
.. configuration-block::
3833

@@ -58,6 +53,7 @@ Now you can configure the routes:
5853
5954
/**
6055
* Matches /blog/*
56+
* but not /blog/slug/extra-part
6157
*
6258
* @Route("/blog/{slug}", name="blog_show")
6359
*/
@@ -74,10 +70,13 @@ Now you can configure the routes:
7470
7571
# config/routes.yaml
7672
blog_list:
73+
# Matches /blog exactly
7774
path: /blog
7875
controller: App\Controller\BlogController::list
7976
8077
blog_show:
78+
# Matches /blog/*
79+
# but not /blog/slug/extra-part
8180
path: /blog/{slug}
8281
controller: App\Controller\BlogController::show
8382
@@ -90,10 +89,13 @@ Now you can configure the routes:
9089
xsi:schemaLocation="http://symfony.com/schema/routing
9190
https://symfony.com/schema/routing/routing-1.0.xsd">
9291
92+
<!-- Matches /blog exactly -->
9393
<route id="blog_list" path="/blog" controller="App\Controller\BlogController::list">
9494
<!-- settings -->
9595
</route>
9696
97+
<!-- Matches /blog/* -->
98+
<!-- but not /blog/slug/extra-part -->
9799
<route id="blog_show" path="/blog/{slug}" controller="App\Controller\BlogController::show">
98100
<!-- settings -->
99101
</route>
@@ -107,9 +109,12 @@ Now you can configure the routes:
107109
use App\Controller\BlogController;
108110
109111
return function (RoutingConfigurator $routes) {
112+
// Matches /blog exactly
110113
$routes->add('blog_list', '/blog')
111114
->controller([BlogController::class, 'list'])
112115
;
116+
// Matches /blog/*
117+
// but not /blog/slug/extra-part
113118
$routes->add('blog_show', '/blog/{slug}')
114119
->controller([BlogController::class, 'show'])
115120
;
@@ -121,13 +126,21 @@ Thanks to these two routes:
121126
is executed;
122127

123128
* If the user goes to ``/blog/*``, the second route is matched and ``show()``
124-
is executed. Because the route path is ``/blog/{slug}``, a ``$slug`` variable is
125-
passed to ``show()`` matching that value. For example, if the user goes to
129+
is executed. Because the route path is ``/blog/{slug}``, a ``$slug`` variable
130+
is passed to ``show()`` matching that value. For example, if the user goes to
126131
``/blog/yay-routing``, then ``$slug`` will equal ``yay-routing``.
127132

128-
Whenever you have a ``{placeholder}`` in your route path, that portion becomes a
129-
wildcard: it matches *any* value. Your controller can now *also* have an argument
130-
called ``$placeholder`` (the wildcard and argument names *must* match).
133+
Whenever you have a ``{placeholder}`` in your route path, that portion becomes
134+
a wildcard: it matches *any* value. Your controller can now *also* have an
135+
argument called ``$placeholder`` (the wildcard and argument names *must*
136+
match).
137+
138+
.. caution::
139+
140+
However the slash ``/`` is ignored by default in placeholder values because
141+
the router uses it as separator between different placeholders.
142+
To learn more about this, you can read
143+
:ref:`routing/slash_in_parameter`.
131144

132145
Each route also has an internal name: ``blog_list`` and ``blog_show``. These can
133146
be anything (as long as each is unique) and don't have any meaning yet. You'll
@@ -936,6 +949,3 @@ Learn more about Routing
936949
:glob:
937950

938951
routing/*
939-
940-
.. _`JMSI18nRoutingBundle`: https://github.com/schmittjoh/JMSI18nRoutingBundle
941-
.. _`BeSimpleI18nRoutingBundle`: https://github.com/BeSimple/BeSimpleI18nRoutingBundle

‎routing/conditions.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@ How to Restrict Route Matching through Conditions
66

77
A route can be made to match only certain routing placeholders (via regular
88
expressions), HTTP methods, or host names. If you need more flexibility to
9-
define arbitrary matching logic, use the ``conditions`` routing option:
9+
define arbitrary matching logic, use the ``condition`` routing setting:
1010

1111
.. configuration-block::
1212

‎routing/custom_route_loader.rst

Lines changed: 11 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -122,11 +122,17 @@ and configure the service and method to call:
122122
$routes->import('admin_route_loader:loadRoutes', 'service');
123123
};
124124
125-
In this example, the routes are loaded by calling the ``loadRoutes()`` method of
126-
the service whose ID is ``admin_route_loader``. Your service doesn't have to
125+
In this example, the routes are loaded by calling the ``loadRoutes()`` method
126+
of the service whose ID is ``admin_route_loader``. Your service doesn't have to
127127
extend or implement any special class, but the called method must return a
128128
:class:`Symfony\\Component\\Routing\\RouteCollection` object.
129129

130+
.. note::
131+
132+
The routes defined using service route loaders will be automatically
133+
cached by the framework. So whenever your service should load new routes,
134+
don't forget to clear the cache.
135+
130136
Creating a custom Loader
131137
------------------------
132138

@@ -240,8 +246,7 @@ Now define a service for the ``ExtraLoader``:
240246
// config/services.php
241247
use App\Routing\ExtraLoader;
242248
243-
$container
244-
->autowire(ExtraLoader::class)
249+
$container->autowire(ExtraLoader::class)
245250
->addTag('routing.loader')
246251
;
247252
@@ -250,7 +255,7 @@ as potential route loaders and added as specialized route loaders to the
250255
``routing.loader`` *service*, which is an instance of
251256
:class:`Symfony\\Bundle\\FrameworkBundle\\Routing\\DelegatingLoader`.
252257

253-
Using the custom Loader
258+
Using the Custom Loader
254259
~~~~~~~~~~~~~~~~~~~~~~~
255260

256261
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).
297302
cached by the framework. So whenever you change something in the loader
298303
class itself, don't forget to clear the cache.
299304

300-
More advanced Loaders
305+
More Advanced Loaders
301306
---------------------
302307

303308
If your custom route loader extends from

0 commit comments

Comments
 (0)