minor #11033 More improvements of the Session article (javiereguiluz)

This PR was merged into the 4.2 branch.

Discussion
----------

More improvements of the Session article

This continues #11027. We now use by default the initial session config created by the recipe: https://github.com/symfony/recipes/blob/master/symfony/framework-bundle/4.2/config/packages/framework.yaml#L10

We also explain things better to fix #8498.

Commits
-------

d02ff77 More improvements of the Session article

Author: javiereguiluz

reference/configuration/framework.rst

@@ -790,18 +790,15 @@ alias will be set to this service id. This class has to implement
 handler_id
 ..........
 
-**type**: ``string`` **default**: ``'session.handler.native_file'``
-
-The service id used for session storage. The ``session.handler`` service
-alias will be set to this service id.
-
-You can also set it to ``null``, to default to the handler of your PHP
-installation.
+**type**: ``string`` **default**: ``null``
 
-.. seealso::
+The service id used for session storage. The default ``null`` value means to use
+the native PHP session mechanism. Set it to ``'session.handler.native_file'`` to
+let Symfony manage the sessions itself using files to store the session
+metadata.
 
-    You can see an example of the usage of this in
-    :doc:`/doctrine/pdo_session_storage`.
+If you prefer to make Symfony store sessions in a database read
+:doc:`/doctrine/pdo_session_storage`.
 
 .. _name:
 

session.rst

@@ -9,7 +9,7 @@ Configuration
 
 Sessions are provided by the `HttpFoundation component`_, which is included in
 all Symfony applications, no matter how you installed it. Before using the
-sessions, check their configuration:
+sessions, check their default configuration:
 
 .. configuration-block::
 
@@ -20,12 +20,12 @@ sessions, check their configuration:
             session:
                 # enables the support of sessions in the app
                 enabled: true
-
-                # ID of the service used for session storage
-                handler_id: session.handler.native_file
-
-                # the directory where session metadata is stored
-                save_path: '%kernel.project_dir%/var/sessions/%kernel.environment%'
+                # ID of the service used for session storage.
+                # NULL =  means that PHP's default session mechanism is used
+                handler_id: null
+                # improves the security of the cookies used for sessions
+                cookie_secure: 'auto'
+                cookie_samesite: 'lax'
 
     .. code-block:: xml
 
@@ -42,11 +42,13 @@ sessions, check their configuration:
                 <!--
                     enabled: enables the support of sessions in the app
                     handler-id: ID of the service used for session storage
-                    save_path: the directory where session metadata is stored
+                                NULL means that PHP's default session mechanism is used
+                    cookie-secure and cookie-samesite: improves the security of the cookies used for sessions
                 -->
                 <framework:session enabled="true"
-                                   handler-id="session.handler.native_file"
-                                   save-path="%kernel.project_dir%/var/sessions/%kernel.environment%" />
+                                   handler-id="null"
+                                   cookie-secure="auto"
+                                   cookie-samesite="lax" />
             </framework:config>
         </container>
 
@@ -58,15 +60,69 @@ sessions, check their configuration:
                 // enables the support of sessions in the app
                 'enabled' => true,
                 // ID of the service used for session storage
+                // NULL means that PHP's default session mechanism is used
+                'handler_id' => null,
+                // improves the security of the cookies used for sessions
+                'cookie_secure' => 'auto',
+                'cookie_samesite' => 'lax',
+            ],
+        ]);
+
+Setting the ``handler_id`` config option to ``null`` means that Symfony will
+use the native PHP session mechanism. The session metadata files will be stored
+outside of the Symfony application, in a directory controlled by PHP. Although
+this usually simplify things, some session expiration related options may no
+work as expected if other applications that write to the same directory have
+short max lifetime settings.
+
+If you prefer, you can use the ``session.handler.native_file`` service as
+``handler_id`` to let Symfony manage the sessions itself. Another useful option
+is ``save_path``, which defines the directory where Symfony will store the
+session metadata files:
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        # config/packages/framework.yaml
+        framework:
+            session:
+                # ...
+                handler_id: 'session.handler.native_file'
+                save_path: '%kernel.project_dir%/var/sessions/%kernel.environment%'
+
+    .. code-block:: xml
+
+        <!-- config/packages/framework.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 enabled="true"
+                                   handler-id="session.handler.native_file"
+                                   save-path="%kernel.project_dir%/var/sessions/%kernel.environment%" />
+            </framework:config>
+        </container>
+
+    .. code-block:: php
+
+        // config/packages/framework.php
+        $container->loadFromExtension('framework', [
+            'session' => [
+                // ...
                 'handler_id' => 'session.handler.native_file',
-                // the directory where session metadata is stored
                 'save_path' => '%kernel.project_dir%/var/sessions/%kernel.environment%',
             ],
         ]);
 
 Check out the Symfony config reference to learn more about the other available
 :ref:`Session configuration options <config-framework-session>`. Also, if you
-prefer to store session metadata in the database instead of the filesystem,
+prefer to store session metadata in a database instead of the filesystem,
 check out this article: :doc:`/doctrine/pdo_session_storage`.
 
 Basic Usage