diff --git a/components/routing.rst b/components/routing.rst index 402c37e06d4..74aa8c4c975 100644 --- a/components/routing.rst +++ b/components/routing.rst @@ -346,6 +346,183 @@ automatically in the background if you want to use it. A basic example of the are saved in the ``cache_dir``. This means your script must have write permissions for that location. +Unicode Routing Support +~~~~~~~~~~~~~~~~~~~~~~~ + +.. versionadded:: 3.2 + UTF-8 support for route paths and requirements was introduced in + Symfony 3.2. + +The Routing component supports UTF-8 characters in route paths and requirements. +Thanks to the ``utf8`` route option, you can make Symfony match and generate +routes with UTF-8 characters: + +.. configuration-block:: + + .. code-block:: php-annotations + + // src/AppBundle/Controller/DefaultController.php + namespace AppBundle\Controller; + + use Symfony\Bundle\FrameworkBundle\Controller\Controller; + use Sensio\Bundle\FrameworkExtraBundle\Configuration\Route; + + class DefaultController extends Controller + { + /** + * + * @Route("/category/{name}", name="route1", options={"utf8": true}) + * + */ + public function categoryAction() + { + // ... + } + + .. code-block:: yaml + + # routes.yml + route1: + path: /category/{name} + defaults: { _controller: 'AppBundle:Default:category' } + options: + utf8: true + + .. code-block:: xml + + + + + + + AppBundle:Default:category + + + + + .. code-block:: php + + // app/config/routing.php + use Symfony\Component\Routing\RouteCollection; + use Symfony\Component\Routing\Route; + + $collection = new RouteCollection(); + $collection->add('route1', new Route('/category/{name}', + array( + '_controller' => 'AppBundle:Default:category', + ), + array(), + array( + 'utf8' => true, + ) + ); + + // ... + + return $collection; + + +In this route, the ``utf8`` option set to ``true`` makes Symfony consider the +``.`` requirement to match any UTF-8 characters instead of just a single +byte character. This means that so the following URLs would match: +``/category/日本語``, ``/category/فارسی``, ``/category/한국어``, etc. In case you +are wondering, this option also allows to include and match emojis in URLs. + +.. configuration-block:: + + .. code-block:: php-annotations + + // src/AppBundle/Controller/DefaultController.php + namespace AppBundle\Controller; + + use Symfony\Bundle\FrameworkBundle\Controller\Controller; + use Sensio\Bundle\FrameworkExtraBundle\Configuration\Route; + + class DefaultController extends Controller + { + /** + * + * @Route( + * "/category/{name}", + * name="route2", + * requirements={"default"="한국어"}, + * options={"utf8": true} + * ) + * + */ + public function defaultAction() + { + // ... + } + + .. code-block:: yaml + + # routes.yml + route2: + path: /default/{default} + defaults: { _controller: 'AppBundle:Default:default' } + requirements: + default: "한국어" + options: + utf8: true + + .. code-block:: xml + + + + + + + AppBundle:Default:default + 한국어 + + + + + .. code-block:: php + + // app/config/routing.php + use Symfony\Component\Routing\RouteCollection; + use Symfony\Component\Routing\Route; + + $collection = new RouteCollection(); + $collection->add('route2', new Route('/default/{default}', + array( + '_controller' => 'AppBundle:Default:default', + ), + array( + 'default' => '한국어', + ), + array( + 'utf8' => true, + ) + ); + + // ... + + return $collection; + + +This second example describes how you can use UTF-8 strings as a routing +requirements. + +.. note:: + + In Symfony 3.2 there is no need to set this ``utf8`` option explicitly. + As soon as Symfony finds a UTF-8 character in the route path or requirements, + it will turn the UTF-8 support automatically. In addition to UTF-8 + characters, the Routing component also supports all the `PCRE Unicode properties`_, + which are escape sequences that match generic character types. For + example, ``\p{Lu}`` matches any uppercase character in any language, + ``\p{Greek}`` matches any Greek character, ``\P{Han}`` matches any character + not included in the Chinese Han script. + Learn more ---------- @@ -360,3 +537,4 @@ Learn more /configuration/apache_router .. _Packagist: https://packagist.org/packages/symfony/routing +.. _PCRE Unicode properties: http://php.net/manual/en/regexp.reference.unicode.php