Merge branch '2.1' into 2.2

Conflicts:
	components/config/definition.rst

Author: weaverryan

book/http_fundamentals.rst

@@ -448,7 +448,7 @@ by adding an entry for ``/contact`` to your routing configuration file:
 
 .. note::
 
-   This example uses :doc:`YAML</components/yaml/introduction>` to define the routing
+   This example uses :doc:`YAML</components/yaml/format>` to define the routing
    configuration. Routing configuration can also be written in other formats
    such as XML or PHP.
 
@@ -458,6 +458,8 @@ the ``AcmeDemoBundle:Main:contact`` string is a short syntax that points to a
 specific PHP method ``contactAction`` inside a class called ``MainController``::
 
     // src/Acme/DemoBundle/Controller/MainController.php
+    namespace Acme\DemoBundle\Controller;
+
     use Symfony\Component\HttpFoundation\Response;
 
     class MainController

components/config/definition.rst

@@ -99,10 +99,10 @@ node definition. Node type are available for:
 
 * scalar
 * boolean
-* array
-* enum (new in 2.1)
 * integer (new in 2.2)
 * float (new in 2.2)
+* enum (new in 2.1)
+* array
 * variable (no validation)
 
 and are created with ``node($name, $type)`` or their associated shortcut
@@ -133,6 +133,25 @@ allowing to validate the value::
         ->end()
     ;
 
+Enum nodes
+~~~~~~~~~~
+
+.. versionadded:: 2.1
+    The enum node is new in Symfony 2.1
+
+Enum nodes provide a constraint to match the given input against a set of
+values::
+
+    $rootNode
+        ->children()
+            ->enumNode('gender')
+                ->values(array('male', 'female'))
+            ->end()
+        ->end()
+    ;
+
+This will restrict the ``gender`` option to be either ``male`` or ``female``.
+
 Array nodes
 ~~~~~~~~~~~
 

cookbook/map.rst.inc

@@ -104,6 +104,7 @@
 * :doc:`/cookbook/request/index`
 
   * :doc:`/cookbook/request/mime_type`
+  * (session) :doc:`/cookbook/session/locale_sticky_session`
 
 * :doc:`/cookbook/routing/index`
 
@@ -137,6 +138,8 @@
 * :doc:`/cookbook/session/index`
 
   * :doc:`/cookbook/session/proxy_examples`
+  * :doc:`/cookbook/session/locale_sticky_session`
+  * :doc:`/cookbook/session/sessions_directory`
 
 * **symfony1**
 

cookbook/routing/custom_route_loader.rst

@@ -66,7 +66,7 @@ type you want. The resource name itself is not actually used in the example::
     namespace Acme\DemoBundle\Routing;
 
     use Symfony\Component\Config\Loader\LoaderInterface;
-    use Symfony\Component\Config\Loader\LoaderResolver;
+    use Symfony\Component\Config\Loader\LoaderResolverInterface;
     use Symfony\Component\Routing\Route;
     use Symfony\Component\Routing\RouteCollection;
 
@@ -110,7 +110,7 @@ type you want. The resource name itself is not actually used in the example::
             // and if you do, using the Loader base class is easier (see below)
         }
 
-        public function setResolver(LoaderResolver $resolver)
+        public function setResolver(LoaderResolverInterface $resolver)
         {
             // same as above
         }

cookbook/session/index.rst

@@ -5,3 +5,5 @@ Sessions
     :maxdepth: 2
 
     proxy_examples
+    locale_sticky_session
+    sessions_directory

cookbook/session/locale_sticky_session.rst

@@ -0,0 +1,103 @@
+.. index::
+    single: Sessions, saving 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, 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 :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;
+
+    use Symfony\Component\HttpKernel\Event\GetResponseEvent;
+    use Symfony\Component\HttpKernel\KernelEvents;
+    use Symfony\Component\EventDispatcher\EventSubscriberInterface;
+
+    class LocaleListener implements EventSubscriberInterface
+    {
+        private $defaultLocale;
+
+        public function __construct($defaultLocale = 'en')
+        {
+            $this->defaultLocale = $defaultLocale;
+        }
+
+        public function onKernelRequest(GetResponseEvent $event)
+        {
+            $request = $event->getRequest();
+            if (!$request->hasPreviousSession()) {
+                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));
+            }
+        }
+
+        public static function getSubscribedEvents()
+        {
+            return array(
+                // must be registered before the default Locale listener
+                KernelEvents::REQUEST => array(array('onKernelRequest', 17)),
+            );
+        }
+    }
+
+Then register the listener:
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        services:
+            acme_locale.locale_listener:
+                class: Acme\LocaleBundle\EventListener\LocaleListener
+                arguments: ["%kernel.default_locale%"]
+                tags:
+                    - { name: kernel.event_subscriber }
+
+    .. code-block:: xml
+
+        <service id="acme_locale.locale_listener"
+            class="Acme\LocaleBundle\EventListener\LocaleListener">
+            <argument>%kernel.default_locale%</argument>
+
+            <tag name="kernel.event_subscriber" />
+        </service>
+
+    .. code-block:: php
+
+        use Symfony\Component\DependencyInjection\Definition;
+
+        $container
+            ->setDefinition('acme_locale.locale_listener', new Definition(
+                'Acme\LocaleBundle\EventListener\LocaleListener',
+                array('%kernel.default_locale%')
+            ))
+            ->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();

cookbook/session/sessions_directory.rst

@@ -0,0 +1,47 @@
+.. index::
+   single: Sessions, sessions directory
+
+Configuring the Directory where Sessions Files are Saved
+========================================================
+
+By default, Symfony stores the session data in the cache directory. This
+means that when you clear the cache, any current sessions will also be
+deleted.
+
+Using a different directory to save session data is one method to ensure
+that your current sessions aren't lost when you clear Symfony's cache.
+
+.. tip::
+
+    Using a different session save handler is an excellent (yet more complex)
+    method of session management available within Symfony. See
+    :doc:`/components/http_foundation/session_configuration` for a
+    discussion of session save handlers. There is also an entry in the cookbook
+    about storing sessions in the :doc:`database</cookbook/configuration/pdo_session_storage>`.
+
+To change the directory in which Symfony saves session data, you only need
+change the framework configuration.  In this example, you will change the
+session directory to ``app/sessions``:
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        # app/config/config.yml
+        framework:
+            session:
+                save_path: "%kernel.root_dir%/sessions"
+
+    .. code-block:: xml
+
+        <!-- app/config/config.xml -->
+        <framework:config>
+            <framework:session save-path="%kernel.root_dir%/sessions" />
+        </framework:config>
+
+    .. code-block:: php
+
+        // app/config/config.php
+        $container->loadFromExtension('framework', array(
+            'session' => array('save-path' => "%kernel.root_dir%/sessions"),
+        ));

quick_tour/the_big_picture.rst

@@ -419,9 +419,9 @@ is the developer's best friend.
 .. image:: /images/quick_tour/web_debug_toolbar.png
    :align: center
 
-But what you see initially is only the tip of the iceberg; click on the weird
-hexadecimal number to reveal yet another very useful Symfony2 debugging tool:
-the profiler.
+But what you see initially is only the tip of the iceberg; click on the long
+hexadecimal number (the session token) to reveal yet another very useful
+Symfony2 debugging tool: the profiler.
 
 .. image:: /images/quick_tour/profiler.png
    :align: center
@@ -433,7 +433,10 @@ the profiler.
 
 Of course, you won't want to show these tools when you deploy your application
 to production. That's why you will find another front controller in the
-``web/`` directory (``app.php``), which is optimized for the production environment:
+``web/`` directory (``app.php``), which is optimized for the production environment.
+The ``AcmeDemoBundle`` is normally only available in the dev environment (see
+the note below), but if you were to add it to the production environment, you
+could go here:
 
 .. code-block:: text
 
@@ -446,7 +449,7 @@ And if you use Apache with ``mod_rewrite`` enabled, you can even omit the
 
     http://localhost/demo/hello/Fabien
 
-Last but not least, on the production servers, you should point your web root
+Last but not least, on production servers, you should point your web root
 directory to the ``web/`` directory to secure your installation and have an
 even better looking URL:
 

reference/configuration/framework.rst

@@ -254,9 +254,11 @@ save_path
 **type**: ``string`` **default**: ``%kernel.cache.dir%/sessions``
 
 This determines the argument to be passed to the save handler. If you choose
-the default file handler, this is the path where the files are created. You can
-also set this value to the ``save_path`` of your ``php.ini`` by setting the
-value to ``null``:
+the default file handler, this is the path where the session files are created.
+For more information, see :doc:`/cookbook/session/sessions_directory`.
+
+You can also set this value to the ``save_path`` of your ``php.ini`` by setting
+the value to ``null``:
 
 .. configuration-block::