[#3276] Trying to further clarify the session storage directory details

cookbook/session/sessions_directory.rst

@@ -4,23 +4,84 @@
 Configuring the Directory Where Sessions Files are Saved
 ========================================================
 
-By default, Symfony stores the session data in files in the cache
-directory ``%kernel.cache_dir%/sessions``. This means that when you clear
-the cache, any current sessions will also be deleted.
+By default, the Symfony Standard Edition uses the global ``php.ini`` values
+for ``session.save_handler`` and ``session.save_path`` to determine where
+to store session data. This is because of the following configuration:
 
-.. note::
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        # app/config/config.yml
+        framework:
+            session:
+                # handler_id set to null will use default session handler from php.ini
+                handler_id:  ~
+
+    .. 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"
+            xmlns:framework="http://symfony.com/schema/dic/symfony"
+            xsi:schemaLocation="http://symfony.com/schema/dic/services
+                http://symfony.com/schema/dic/services/services-1.0.xsd
+                http://symfony.com/schema/dic/symfony
+                http://symfony.com/schema/dic/symfony/symfony-1.0.xsd"
+        >
+            <framework:config>
+                <framework:session handler-id="null" />
+            </framework:config>
+        </container>
 
-    If the ``session`` configuration key is set to ``~``, Symfony will use the
-    global PHP ini values for ``session.save_handler`` and associated
-    ``session.save_path`` from ``php.ini``.
+    .. code-block:: php
+
+        // app/config/config.php
+        $container->loadFromExtension('framework', array(
+            'session' => array(
+                'handler-id' => null,
+            ),
+        ));
 
-.. note::
+With this configuration, changing *where* your session metadata is stored
+is entirely up to your ``php.ini`` configuration.
 
-    While the Symfony Full Stack Framework defaults to using the
-    ``session.handler.native_file``, the Symfony Standard Edition is
-    configured to use PHP's global session settings by default and therefor
-    sessions will be stored according to the ``session.save_path`` location
-    and will not be deleted when clearing the cache.
+However, if you have the following configuration, Symfony will store the session
+data in files in the cache directory ``%kernel.cache_dir%/sessions``. This
+means that when you clear the cache, any current sessions will also be deleted:
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        # app/config/config.yml
+        framework:
+            session: ~
+
+    .. 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"
+            xmlns:framework="http://symfony.com/schema/dic/symfony"
+            xsi:schemaLocation="http://symfony.com/schema/dic/services
+                http://symfony.com/schema/dic/services/services-1.0.xsd
+                http://symfony.com/schema/dic/symfony
+                http://symfony.com/schema/dic/symfony/symfony-1.0.xsd"
+        >
+            <framework:config>
+                <framework:session />
+            </framework:config>
+        </container>
+
+    .. code-block:: php
+
+        // app/config/config.php
+        $container->loadFromExtension('framework', array(
+            'session' => array(),
+        ));
 
 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.