Updated the session proxy article

cookbook/session/proxy_examples.rst

@@ -4,26 +4,92 @@
 Session Proxy Examples
 ======================
 
-The session proxy mechanism has a variety of uses and this example demonstrates
-two common uses. Rather than injecting the session handler as normal, a handler
-is injected into the proxy and registered with the session storage driver::
+The session proxy mechanism has a variety of uses and this article demonstrates
+two common uses. Rather than using the regular session handler, you can create
+a custom save handler just by defining a class that extends the
+:class:`Symfony\\Component\\HttpFoundation\\Session\\Storage\\Proxy\\SessionHandlerProxy`
+class.
 
-    use Symfony\Component\HttpFoundation\Session\Session;
-    use Symfony\Component\HttpFoundation\Session\Storage\NativeSessionStorage;
-    use Symfony\Component\HttpFoundation\Session\Storage\Handler\PdoSessionHandler;
+Then, define a new service related to the custom session handler:
 
-    $proxy = new YourProxy(new PdoSessionHandler());
-    $session = new Session(new NativeSessionStorage(array(), $proxy));
+.. configuration-block::
 
-Below, you'll learn two real examples that can be used for ``YourProxy``:
-encryption of session data and readonly guest sessions.
+    .. code-block:: yaml
+
+        # app/config/services.yml
+        services:
+            app.session_handler:
+                class: AppBundle\Session\CustomSessionHandler
+
+    .. code-block:: xml
+
+        <!-- app/config/services.xml -->
+        <?xml version="1.0" encoding="UTF-8" ?>
+        <container xmlns="http://symfony.com/schema/dic/services"
+            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+            xsi:schemaLocation="http://symfony.com/schema/dic/services
+                http://symfony.com/schema/dic/services/services-1.0.xsd">
+
+            <services>
+                <service id="app.session_handler" class="AppBundle\Session\CustomSessionHandler" />
+            </services>
+        </container>
+
+    .. code-block:: php
+
+        // app/config/config.php
+        $container->register('app.session_handler', 'AppBundle\Session\CustomSessionHandler');
+
+Finally, use the ``framework.session.handler_id`` configuration option to tell
+Symfony to use your own session handler instead of the default one:
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        # app/config/config.yml
+        framework:
+            session:
+                # ...
+                handler_id: app.session_handler
+
+    .. code-block:: xml
+
+        <!-- app/config/config.xml -->
+        <?xml version="1.0" encoding="UTF-8" ?>
+        <container xmlns="http://symfony.com/schema/dic/services"
+            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+            xsi:schemaLocation="http://symfony.com/schema/dic/services
+                http://symfony.com/schema/dic/services/services-1.0.xsd">
+            <framework:config>
+                <framework:session handler-id="app.session_handler" ... />
+            </framework:config>
+        </container>
+
+    .. code-block:: php
+
+        // app/config/config.php
+        $container->loadFromExtension('framework', array(
+            // ...
+            'session' => array(
+                // ...
+                'handler_id' => 'app.session_handler',
+            ),
+        ));
+
+Keep reading the next sections to learn how to use the session handlers in practice
+to solve two common use cases: encrypt session information and define readonly
+guest sessions.
 
 Encryption of Session Data
 --------------------------
 
 If you wanted to encrypt the session data, you could use the proxy to encrypt
 and decrypt the session as required::
 
+    // src/AppBundle/Session/EncryptedSessionProxy.php
+    namespace AppBundle\Session;
+
     use Symfony\Component\HttpFoundation\Session\Storage\Proxy\SessionHandlerProxy;
 
     class EncryptedSessionProxy extends SessionHandlerProxy
@@ -59,10 +125,13 @@ There are some applications where a session is required for guest users, but
 where there is no particular need to persist the session. In this case you
 can intercept the session before it is written::
 
-    use Foo\User;
+    // src/AppBundle/Session/ReadOnlySessionProxy.php
+    namespace AppBundle\Session;
+
+    use AppBundle\Entity\User;
     use Symfony\Component\HttpFoundation\Session\Storage\Proxy\SessionHandlerProxy;
 
-    class ReadOnlyGuestSessionProxy extends SessionHandlerProxy
+    class ReadOnlySessionProxy extends SessionHandlerProxy
     {
         private $user;