Merge pull request symfony#3342 from drak/session_c

weaverryan · weaverryan · commit a3d5c6cebe87 · 2014-01-01T15:06:26.000-08:00
Clarify settings for native file storage
diff --git a/cookbook/session/sessions_directory.rst b/cookbook/session/sessions_directory.rst
@@ -1,12 +1,26 @@
 .. index::
    single: Sessions, sessions directory
 
-Configuring the Directory where Sessions Files are Saved
+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.
+By default, Symfony stores the session data in files in the cache
+directory ``%kernel.cach_dir%/sessions``. This means that when you clear
+the cache, any current sessions will also be deleted.
+
+.. note::
+
+    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``.
+
+.. note::
+
+    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.
 
 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.
@@ -30,18 +44,24 @@ session directory to ``app/sessions``:
         # app/config/config.yml
         framework:
             session:
+                handler_id: session.handler.native_file
                 save_path: "%kernel.root_dir%/sessions"
 
     .. code-block:: xml
 
         <!-- app/config/config.xml -->
         <framework:config>
+            <framework:session handler-id="session.handler.native_file" />
             <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"),
+            'session' => array(
+                'handler-id' => 'session.handler.native_file',
+                'save-path' => '%kernel.root_dir%/sessions',
+            ),
         ));
+        
