Document new utf8 option of Routing component #6938

mickaelandrieu · 2016-09-01T08:55:26Z

Hi,

all credits to @javiereguiluz and @nicolas-grekas, I've just copy/pasted the blog article http://symfony.com/blog/new-in-symfony-3-2-unicode-routing-support#comment-form

Mickaël

nicolas-grekas · 2016-09-01T08:58:54Z

See #6890
we now have to decide which one is better :)

nicolas-grekas · 2016-09-01T08:59:55Z

or merge both since they aren't on the same page

mickaelandrieu · 2016-09-01T11:59:03Z

@nicolas-grekas my bad, didnt thank you have started something... as you like, I wont be sad if you close this one, my only interest is to see this feature documented ^^

By the way, big thanks! From a business/e-commerce point of view, this feature is so useful :)

xabbuh · 2016-09-21T19:58:21Z

components/routing.rst

@@ -346,6 +346,44 @@ 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


Unicode Routing Support

xabbuh · 2016-09-21T19:58:37Z

components/routing.rst

+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:


Routing component

The option needs to be enclosed by double backticks.

Please also wrap lines after the first word that crosses the 72nd character.

xabbuh · 2016-09-21T19:59:23Z

components/routing.rst

+        requirements:
+          name: ".+"
+        options:
+          utf8: true


Please add Annotations, XML, and PHP examples too.

xabbuh · 2016-09-21T19:59:44Z

components/routing.rst

+        options:
+          utf8: true
+
+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.


please use double backticks everywhere here too

and please wrap lines after the first word that crosses the 72nd character

xabbuh · 2016-09-21T20:00:43Z

components/routing.rst

+        requirements:
+          default: "日本語|فارسی"
+        options:
+          utf8: true


We need other format examples here too.

Do we really need ? I don't see the gain here when it's already well described here

I will do it if you insist, though (sounds like a simple copy/paste of the resource I've linked ^ ).

That's how the doc is yes, config are always in all formats, repeating is teaching isn't it?

true, let's go for it :)

xabbuh · 2016-09-21T20:00:52Z

components/routing.rst

+        options:
+          utf8: true
+
+This second example describes how you can use utf8 string as a routing requirement.


xabbuh · 2016-09-21T20:01:02Z

components/routing.rst

+
+.. 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.


same as above

xabbuh · 2016-09-21T20:01:26Z

components/routing.rst

+    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
+    The UTF8 support in route paths and requirements were added in Symfony 3.2


UTF-8 support for route paths and requirements were introduced in Symfony 3.2.

mickaelandrieu · 2016-09-21T21:43:29Z

Wow ... I feel so bad :( thank you for this review, I will address comments tomorrow!

xabbuh · 2016-09-21T22:03:07Z

No need to worry. There's not much to change. :)

mickaelandrieu · 2016-09-22T12:57:21Z

Hi @xabbuh,

I've adressed almost all comments except the one about complete all formats, let me know if this need more work :)

Mickaël

xabbuh · 2016-09-22T13:16:19Z

👍 (except for the missing config formats)

mickaelandrieu · 2016-09-22T13:31:38Z

components/routing.rst

+
+            <route id="route1" path="/category/{name}">
+                <default key="_controller">AppBundle:Default:category</default>
+                <option key="utf8">true</option>


Question here: how can we do to ensure true will be converted to boolean value ?

That's the responsibility of the loader.

So ... is it good, or does it need much work from me ?

It's good as it is. :)

xabbuh · 2016-09-25T07:54:15Z

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


xabbuh · 2016-09-25T07:54:38Z

components/routing.rst

+          path:     /category/{name}
+          defaults: { _controller: 'DefaultController::categoryAction' }
+          options:
+            utf8: true


please indent this line with four spaces

xabbuh · 2016-09-25T07:55:18Z

components/routing.rst

+      # routes.yml
+      route1:
+          path:     /category/{name}
+          defaults: { _controller: 'DefaultController::categoryAction' }


AppBundle:Default:category

xabbuh · 2016-09-25T07:56:07Z

components/routing.rst

+      return $collection;
+
+
+In this route, the ``utf8`` option set to true makes Symfony consider the


please enclose true in double backticks

xabbuh · 2016-09-25T07:56:41Z

components/routing.rst

+
+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/日本語``,


maybe split this here: "[...] character. This means that the following URL would match [...]"

xabbuh · 2016-09-25T07:57:05Z

components/routing.rst

+
+.. configuration-block::
+
+  .. code-block:: php-annotations


please indent with four spaces

xabbuh · 2016-09-25T07:57:37Z

components/routing.rst

+      return $collection;
+
+
+This second example describes how you can use UTF-8 string as a routing


[...] as routing requirements.

xabbuh · 2016-09-25T07:58:06Z

components/routing.rst

+
+.. note::
+
+    In Symfony 3.2 there is no need to set this utf8 explicitly. As soon


[...] to explicitly set the utf8 option.

xabbuh · 2016-09-25T07:58:27Z

components/routing.rst

+
+.. versionadded:: 3.2
+    UTF-8 support for route paths and requirements were introduced in
+    Symfony 3.2.


I would move this up to the beginning of this section.

mickaelandrieu · 2016-09-27T21:08:22Z

@xabbuh thanks again for your time. Comments addressed ;)

xabbuh · 2016-09-28T07:52:38Z

components/routing.rst

+~~~~~~~~~~~~~~~~~~~~~~~
+
+.. versionadded:: 3.2
+    UTF-8 support for route paths and requirements were introduced in


xabbuh · 2016-09-28T07:53:05Z

components/routing.rst

+          path:     /category/{name}
+          defaults: { _controller: 'AppBundle:Default:category' }
+          options:
+            utf8: true


indentation :)

Looks like it's the same in the other YAML example too.

xabbuh · 2016-09-28T07:54:57Z

@mickaelandrieu I left two last minor comments and indentation of the PHP code examples looks weird too. But overall this change looks ready to be merged. 👍

mickaelandrieu · 2016-09-28T07:58:05Z

@xabbuh I won't give up now :D let me improve again my contribution ;)

edit: comments addressed (and PHP code cs fixed)

xabbuh · 2016-09-28T17:31:28Z

👍

Status: Reviewed

@javiereguiluz

…ndrieu) This PR was merged into the master branch. Discussion ---------- Document new utf8 option of Routing component Hi, all credits to @javiereguiluz and @nicolas-grekas, I've just copy/pasted the blog article http://symfony.com/blog/new-in-symfony-3-2-unicode-routing-support#comment-form Mickaël Commits ------- 2569aca Document new utf8 option of Routing component

wouterj · 2016-10-06T21:31:55Z

Thanks @mickaelandrieu! After your quick responses to the reviews, this PR has now made it to the docs!

Fyi, I've fixed some indentation issues and splitted the big note directive in c5328d7.

mickaelandrieu · 2016-10-06T23:31:37Z

@wouterj thank you, it's better now :)
Always happy to help ;)

This PR was merged into the master branch. Discussion ---------- [#6938] tweak the wording a bit Commits ------- 9348ccf [#6938] tweak the wording a bit

xabbuh reviewed Sep 21, 2016

View reviewed changes

xabbuh requested changes Sep 21, 2016

View reviewed changes

xabbuh added Routing Status: Needs Work labels Sep 21, 2016

mickaelandrieu force-pushed the patch-4 branch from 991b4b6 to cf8ab0f Compare September 22, 2016 12:55

carsonbot added Status: Needs Review and removed Status: Needs Work labels Sep 22, 2016

mickaelandrieu force-pushed the patch-4 branch from cf8ab0f to c542f01 Compare September 22, 2016 13:28

mickaelandrieu commented Sep 22, 2016

View reviewed changes

xabbuh reviewed Sep 25, 2016

View reviewed changes

components/routing.rst

.. configuration-block::

.. code-block:: php-annotations

Copy link

Member

xabbuh Sep 25, 2016

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

please indent with four spaces

xabbuh reviewed Sep 25, 2016

View reviewed changes

mickaelandrieu force-pushed the patch-4 branch 2 times, most recently from bbd2931 to 19a864f Compare September 27, 2016 21:07

xabbuh reviewed Sep 28, 2016

View reviewed changes

Document new utf8 option of Routing component

2569aca

mickaelandrieu force-pushed the patch-4 branch from 19a864f to 2569aca Compare September 28, 2016 12:08

xabbuh approved these changes Sep 28, 2016

View reviewed changes

carsonbot added Status: Reviewed and removed Status: Needs Review labels Sep 28, 2016

wouterj merged commit 2569aca into symfony:master Oct 6, 2016

wouterj added a commit that referenced this pull request Oct 6, 2016

[#6938] Syntax error fixes and splitting the big note

c5328d7

mickaelandrieu deleted the patch-4 branch October 6, 2016 23:31

xabbuh added a commit to xabbuh/symfony-docs that referenced this pull request Oct 7, 2016

[symfony#6938] tweak the wording a bit

9348ccf

wouterj added a commit that referenced this pull request Oct 20, 2016

minor #7048 [#6938] tweak the wording a bit (xabbuh)

37066fa

This PR was merged into the master branch. Discussion ---------- [#6938] tweak the wording a bit Commits ------- 9348ccf [#6938] tweak the wording a bit


		.. 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.

		return $collection;


		In this route, the ``utf8`` option set to true makes Symfony consider the

		return $collection;


		This second example describes how you can use UTF-8 string as a routing

Document new utf8 option of Routing component #6938

Document new utf8 option of Routing component #6938

Conversation

mickaelandrieu commented Sep 1, 2016

nicolas-grekas commented Sep 1, 2016

nicolas-grekas commented Sep 1, 2016

mickaelandrieu commented Sep 1, 2016 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

mickaelandrieu commented Sep 21, 2016

xabbuh commented Sep 21, 2016

mickaelandrieu commented Sep 22, 2016

xabbuh commented Sep 22, 2016

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

mickaelandrieu commented Sep 27, 2016

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

xabbuh commented Sep 28, 2016

mickaelandrieu commented Sep 28, 2016 • edited Loading

xabbuh commented Sep 28, 2016

wouterj commented Oct 6, 2016

mickaelandrieu commented Oct 6, 2016

mickaelandrieu commented Sep 1, 2016 •

edited

Loading

mickaelandrieu commented Sep 28, 2016 •

edited

Loading