[symfony#2662] Tweaks to new sticky locale cookbook by @wouterj

weaverryan · weaverryan · commit ba7ab6fef164 · 2013-06-30T13:57:24.000-05:00
The name was changed only because 2.1 is end-of-life, and I think it's more interesting how to know how to make your locale sticky, and less important that this was the old behavior.
diff --git a/cookbook/map.rst.inc b/cookbook/map.rst.inc
@@ -102,7 +102,7 @@
 * :doc:`/cookbook/request/index`
 
   * :doc:`/cookbook/request/mime_type`
-  * (session) :doc:`/cookbook/session/simulate_locale_in_session`
+  * (session) :doc:`/cookbook/session/locale_sticky_session`
 
 * :doc:`/cookbook/routing/index`
 
@@ -136,7 +136,7 @@
 * :doc:`/cookbook/session/index`
 
   * :doc:`/cookbook/session/proxy_examples`
-  * :doc:`/cookbook/session/simulate_locale_in_session`
+  * :doc:`/cookbook/session/locale_sticky_session`
 
 * **symfony1**
 
diff --git a/cookbook/session/index.rst b/cookbook/session/index.rst
@@ -5,4 +5,4 @@ Sessions
     :maxdepth: 2
 
     proxy_examples
-    simulate_locale_in_session
+    locale_sticky_session
diff --git a/cookbook/session/locale_sticky_session.rst b/cookbook/session/locale_sticky_session.rst
@@ -1,20 +1,23 @@
 .. index::
     single: Sessions, saving locale
 
-Simulate old Behaviour of Saving the Locale
-===========================================
+Making the Locale "Sticky" during a User's Session
+==================================================
 
 Prior to Symfony 2.1, the locale was stored in a session called ``_locale``.
-Since 2.1, it is stored in the Request. You'll learn how to simulate the old
-way in this article.
+Since 2.1, it is stored in the Request, which means that it's not "sticky"
+during a user's request. In this article, you'll learn how to make the locale
+of a user "sticky" so that once it's set, that same locale will be used for
+every subsequent request.
 
 Creating LocaleListener
 -----------------------
 
 To simulate that the locale is stored in a session, you need to create and
-register a new listener. The listener will look like the following, assuming
-that the parameter which handels the locale value in the request is called
-``_locale``::
+register a :doc:`new event listener</cookbook/service_container/event_listener>`.
+The listener will look something like this. Typically, ``_locale`` is used
+as a routing parameter to signify the locale, though it doesn't really matter
+how you determine the desired locale from the request::
 
     // src/Acme/LocaleBundle/EventListener/LocaleListener.php
     namespace Acme\LocaleBundle\EventListener;
@@ -39,9 +42,11 @@ that the parameter which handels the locale value in the request is called
                 return;
             }
 
+            // try to see if the locale has been set as a _locale routing parameter
             if ($locale = $request->attributes->get('_locale')) {
                 $request->getSession()->set('_locale', $locale);
             } else {
+                // if no explicit locale has been set on this request, use one from the session
                 $request->setLocale($request->getSession()->get('_locale', $this->defaultLocale));
             }
         }
@@ -88,3 +93,11 @@ Then register the listener:
             ))
             ->addTag('kernel.event_subscriber')
         ;
+
+That's it! Now celebrate by changing the user's locale and seeing that it's
+sticky throughout the request. Remember, to get the user's locale, always
+use the :method:`Request::getLocale<Symfony\\Component\\HttpFoundation\\Request::getLocale>`
+method::
+
+    // from a controller...
+    $locale = $this->getRequest()->getLocale();
