Document new utf8 option of Routing component

Author: mickaelandrieu

components/routing.rst

@@ -346,6 +346,181 @@ 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
+~~~~~~~~~~~~~~~~~~~~~~~
+
+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: 'DefaultController::categoryAction' }
+          options:
+            utf8: true
+
+  .. code-block:: xml
+
+        <!-- app/config/routing.xml -->
+        <?xml version="1.0" encoding="UTF-8" ?>
+        <routes xmlns="http://symfony.com/schema/routing"
+            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+            xsi:schemaLocation="http://symfony.com/schema/routing
+                http://symfony.com/schema/routing/routing-1.0.xsd">
+
+            <route id="route1" path="/category/{name}">
+                <default key="_controller">AppBundle:Default:category</default>
+                <option key="utf8">true</option>
+            </route>
+        </routes>
+
+  .. 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, 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: 'DefaultController::defaultAction' }
+          requirements:
+            default: "한국어"
+          options:
+            utf8: true
+
+  .. code-block:: xml
+
+        <!-- app/config/routing.xml -->
+        <?xml version="1.0" encoding="UTF-8" ?>
+        <routes xmlns="http://symfony.com/schema/routing"
+            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+            xsi:schemaLocation="http://symfony.com/schema/routing
+                http://symfony.com/schema/routing/routing-1.0.xsd">
+
+            <route id="route2" path="/default/{default}">
+                <default key="_controller">AppBundle:Default:default</default>
+                <requirement key="default">한국어</requirement>
+                <option key="utf8">true</option>
+            </route>
+        </routes>
+
+  .. 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 string as a routing
+requirement.
+
+.. note::
+
+    In Symfony 3.2 there is no need to set this utf8 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.
+
+.. versionadded:: 3.2
+    UTF-8 support for route paths and requirements were introduced in
+    Symfony 3.2.
+
 Learn more
 ----------
 
@@ -360,3 +535,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