Skip to content

Commit b7387b5

Browse files
javiereguiluzjaviereguiluz
committed
minor #11126 [Routing][DX] Exposed "utf8" options, and defaults "locale" and "format" (Jules Pietri, HeahDude)
This PR was merged into the master branch. Discussion ---------- [Routing][DX] Exposed "utf8" options, and defaults "locale" and "format" Documentation for symfony/symfony#30508 Commits ------- f9e2eaa fixup f1eae44 added doc for defaults 06a71a9 [Routing][DX] Exposed "compiler_class" and "utf8" options
2 parents d24bb04 + f9e2eaa commit b7387b5

File tree

2 files changed

+157
-18
lines changed

2 files changed

+157
-18
lines changed

‎components/routing.rst

Lines changed: 65 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -399,7 +399,7 @@ routes with UTF-8 characters:
399399
class DefaultController extends AbstractController
400400
{
401401
/**
402-
* @Route("/category/{name}", name="route1", options={"utf8": true})
402+
* @Route("/category/{name}", name="route1", utf8=true)
403403
*/
404404
public function category()
405405
{
@@ -411,8 +411,7 @@ routes with UTF-8 characters:
411411
route1:
412412
path: /category/{name}
413413
controller: App\Controller\DefaultController::category
414-
options:
415-
utf8: true
414+
utf8: true
416415
417416
.. code-block:: xml
418417
@@ -422,9 +421,10 @@ routes with UTF-8 characters:
422421
xsi:schemaLocation="http://symfony.com/schema/routing
423422
https://symfony.com/schema/routing/routing-1.0.xsd">
424423
425-
<route id="route1" path="/category/{name}" controller="App\Controller\DefaultController::category">
426-
<option key="utf8">true</option>
427-
</route>
424+
<route id="route1"
425+
path="/category/{name}"
426+
controller="App\Controller\DefaultController::category"
427+
utf8="true" />
428428
</routes>
429429
430430
.. code-block:: php
@@ -437,12 +437,61 @@ routes with UTF-8 characters:
437437
return function (RoutingConfigurator $routes) {
438438
$routes->add('route1', '/category/{name}')
439439
->controller([DefaultController::class, 'category'])
440-
->options([
441-
'utf8' => true,
442-
])
440+
->utf8()
443441
;
444442
};
445443
444+
.. versionadded:: 4.3
445+
446+
The ``utf8`` shortcut has been introduced in Symfony 4.3.
447+
Before you has to use the ``options`` setting to define
448+
this value:
449+
450+
.. configuration-block::
451+
452+
.. code-block:: php-annotations
453+
454+
route1:
455+
path: /category/{name}
456+
controller: App\Controller\DefaultController::category
457+
options: { utf8: true }
458+
459+
.. code-block:: yaml
460+
461+
route1:
462+
path: /category/{name}
463+
controller: App\Controller\DefaultController::category
464+
utf8: true
465+
466+
.. code-block:: xml
467+
468+
<?xml version="1.0" encoding="UTF-8" ?>
469+
<routes xmlns="http://symfony.com/schema/routing"
470+
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
471+
xsi:schemaLocation="http://symfony.com/schema/routing
472+
http://symfony.com/schema/routing/routing-1.0.xsd">
473+
474+
<route id="route1"
475+
path="/category/{name}"
476+
controller="App\Controller\DefaultController::category" >
477+
<option key="utf8">true</option>
478+
</route>
479+
</routes>
480+
481+
.. code-block:: php
482+
483+
// config/routes.php
484+
namespace Symfony\Component\Routing\Loader\Configurator;
485+
486+
use App\Controller\DefaultController;
487+
488+
return function (RoutingConfigurator $routes) {
489+
$routes->add('route1', '/category/{name}')
490+
->controller([DefaultController::class, 'category'])
491+
->options(['utf8' => true])
492+
;
493+
};
494+
446495
In this route, the ``utf8`` option set to ``true`` makes Symfony consider the
447496
``.`` requirement to match any UTF-8 characters instead of just a single
448497
byte character. This means that so the following URLs would match:
@@ -467,7 +516,7 @@ You can also include UTF-8 strings as routing requirements:
467516
* "/category/{name}",
468517
* name="route2",
469518
* defaults={"name"="한국어"},
470-
* options={"utf8": true}
519+
* utf8=true
471520
* )
472521
*/
473522
public function category()
@@ -482,8 +531,7 @@ You can also include UTF-8 strings as routing requirements:
482531
controller: 'App\Controller\DefaultController::category'
483532
defaults:
484533
name: "한국어"
485-
options:
486-
utf8: true
534+
utf8: true
487535
488536
.. code-block:: xml
489537
@@ -493,9 +541,11 @@ You can also include UTF-8 strings as routing requirements:
493541
xsi:schemaLocation="http://symfony.com/schema/routing
494542
https://symfony.com/schema/routing/routing-1.0.xsd">
495543
496-
<route id="route2" path="/category/{name}" controller="App\Controller\DefaultController::category">
544+
<route id="route2"
545+
path="/category/{name}"
546+
controller="App\Controller\DefaultController::category"
547+
utf8="true" >
497548
<default key="name">한국어</default>
498-
<option key="utf8">true</option>
499549
</route>
500550
</routes>
501551
@@ -512,9 +562,7 @@ You can also include UTF-8 strings as routing requirements:
512562
->defaults([
513563
'name' => '한국어',
514564
])
515-
->options([
516-
'utf8' => true,
517-
])
565+
->utf8()
518566
;
519567
};
520568

‎routing.rst

Lines changed: 92 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -623,7 +623,10 @@ With all of this in mind, check out this advanced example:
623623
/**
624624
* @Route(
625625
* "/articles/{_locale}/{year}/{slug}.{_format}",
626-
* defaults={"_format": "html"},
626+
* defaults={
627+
* "_locale": "en",
628+
* "_format": "html"
629+
* },
627630
* requirements={
628631
* "_locale": "en|fr",
629632
* "_format": "html|rss",
@@ -643,6 +646,7 @@ With all of this in mind, check out this advanced example:
643646
path: /articles/{_locale}/{year}/{slug}.{_format}
644647
controller: App\Controller\ArticleController::show
645648
defaults:
649+
_locale: en
646650
_format: html
647651
requirements:
648652
_locale: en|fr
@@ -662,6 +666,7 @@ With all of this in mind, check out this advanced example:
662666
path="/articles/{_locale}/{year}/{slug}.{_format}"
663667
controller="App\Controller\ArticleController::show">
664668
669+
<default key="_locale">en</default>
665670
<default key="_format">html</default>
666671
<requirement key="_locale">en|fr</requirement>
667672
<requirement key="_format">html|rss</requirement>
@@ -681,6 +686,7 @@ With all of this in mind, check out this advanced example:
681686
$routes->add('article_show', '/articles/{_locale}/{year}/{slug}.{_format}')
682687
->controller([ArticleController::class, 'show'])
683688
->defaults([
689+
'_locale' => 'en',
684690
'_format' => 'html',
685691
])
686692
->requirements([
@@ -739,6 +745,91 @@ that are special: each adds a unique piece of functionality inside your applicat
739745
``_locale``
740746
Used to set the locale on the request (:ref:`read more <translation-locale-url>`).
741747

748+
You can also use special attributes to configure them (except ``_fragment``):
749+
750+
.. configuration-block::
751+
752+
.. code-block:: php-annotations
753+
754+
// src/Controller/ArticleController.php
755+
756+
// ...
757+
class ArticleController extends AbstractController
758+
{
759+
/**
760+
* @Route(
761+
* "/articles/{_locale}/search.{_format}",
762+
* locale="en",
763+
* format="html",
764+
* requirements={
765+
* "_locale": "en|fr",
766+
* "_format": "html|xml",
767+
* }
768+
* )
769+
*/
770+
public function search()
771+
{
772+
}
773+
}
774+
775+
.. code-block:: yaml
776+
777+
# config/routes.yaml
778+
article_search:
779+
path: /articles/{_locale}/search.{_format}
780+
controller: App\Controller\ArticleController::search
781+
locale: en
782+
format: html
783+
requirements:
784+
_locale: en|fr
785+
_format: html|xml
786+
787+
.. code-block:: xml
788+
789+
<!-- config/routes.xml -->
790+
<?xml version="1.0" encoding="UTF-8" ?>
791+
<routes xmlns="http://symfony.com/schema/routing"
792+
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
793+
xsi:schemaLocation="http://symfony.com/schema/routing
794+
http://symfony.com/schema/routing/routing-1.0.xsd">
795+
796+
<route id="article_search"
797+
path="/articles/{_locale}/search.{_format}"
798+
controller="App\Controller\ArticleController::search"
799+
locale="en"
800+
format="html">
801+
802+
<requirement key="_locale">en|fr</requirement>
803+
<requirement key="_format">html|rss</requirement>
804+
805+
</route>
806+
</routes>
807+
808+
.. code-block:: php
809+
810+
// config/routes.php
811+
namespace Symfony\Component\Routing\Loader\Configurator;
812+
813+
use App\Controller\ArticleController;
814+
815+
return function (RoutingConfigurator $routes) {
816+
$routes->add('article_show', '/articles/{_locale}/search.{_format}')
817+
->controller([ArticleController::class, 'search'])
818+
->locale('en')
819+
->format('html)
820+
->requirements([
821+
'_locale' => 'en|fr',
822+
'_format' => 'html|rss',
823+
])
824+
;
825+
};
826+
827+
Those attributes can also be used for imports.
828+
829+
.. versionadded::
830+
831+
The special attributes has been introduced in Symfony 4.3.
832+
742833
.. _routing-trailing-slash-redirection:
743834

744835
Redirecting URLs with Trailing Slashes

0 commit comments

Comments
 (0)