minor #11027 Revamped the reference article for Sessions (javiereguiluz)

This PR was squashed before being merged into the 4.2 branch (closes #11027).

Discussion
----------

Revamped the reference article for Sessions

Similar to recent pull requests, this revamps an article which is very poor at the moment (https://symfony.com/doc/current/session.html) adding all the basics about it, including the contents of some micro-articles that have been removed.

Fixes #8740.

Commits
-------

41f81fe Revamped the reference article for Sessions

Author: javiereguiluz

_build/redirection_map

@@ -409,3 +409,5 @@
 /profiler/profiling_data /profiler
 /profiler/wdt_follow_ajax /profiler
 /security/entity_provider /security/user_provider
+/session/avoid_session_start /session
+/session/sessions_directory /session

controller.rst

@@ -405,16 +405,13 @@ To get the session, add an argument and type-hint it with
 
 Stored attributes remain in the session for the remainder of that user's session.
 
-.. tip::
-
-    Every ``SessionInterface`` implementation is supported. If you have your
-    own implementation, type-hint this in the argument instead.
-
 For more info, see :doc:`/session`.
 
 .. index::
    single: Session; Flash messages
 
+.. _flash-messages:
+
 Flash Messages
 ~~~~~~~~~~~~~~
 

http_cache/varnish.rst

@@ -63,7 +63,7 @@ authentication, have Varnish remove the corresponding header from requests to
 prevent clients from bypassing the cache. In practice, you will need sessions
 at least for some parts of the site, e.g. when using forms with
 :doc:`CSRF Protection </security/csrf>`. In this situation, make sure to
-:doc:`only start a session when actually needed </session/avoid_session_start>`
+:ref:`only start a session when actually needed <session-avoid-start>`
 and clear the session when it is no longer needed. Alternatively, you can look
 into :ref:`caching pages that contain CSRF protected forms <caching-pages-that-contain-csrf-protected-forms>`.
 

reference/configuration/framework.rst

@@ -906,7 +906,6 @@ save_path
 
 This determines the argument to be passed to the save handler. If you choose
 the default file handler, this is the path where the session files are created.
-For more information, see :doc:`/session/sessions_directory`.
 
 You can also set this value to the ``save_path`` of your ``php.ini`` by
 setting the value to ``null``:

session.rst

@@ -1,21 +1,149 @@
 Sessions
 ========
 
-Symfony provides a nice session object that you can use to store information
-about the user between requests.
+Symfony provides a session object and several utilities that you can use to
+store information about the user between requests.
 
-To see how to use the session, read :ref:`session-intro`.
+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:
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        # config/packages/framework.yaml
+        framework:
+            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%'
+
+    .. 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>
+                <!--
+                    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
+                -->
+                <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' => [
+                // 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%',
+            ],
+        ]);
+
+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,
+check out this article: :doc:`/doctrine/pdo_session_storage`.
+
+Basic Usage
+-----------
+
+Symfony provides a session service that is injected in your services and
+controllers if you type-hint an argument with
+:class:`Symfony\\Component\\HttpFoundation\\Session\\SessionInterface`::
+
+    use Symfony\Component\HttpFoundation\Session\SessionInterface;
+
+    class SomeService
+    {
+        private $session;
+
+        public function __construct(SessionInterface $session)
+        {
+            $this->session = $session;
+        }
+
+        public function someMethod()
+        {
+            // stores an attribute in the session for later reuse
+            $session->set('attribute-name', 'attribute-value');
+
+            // gets an attribute by name
+            $foo = $session->get('foo');
+
+            // uses a default value if the attribute doesn't exist
+            $filters = $session->get('filters', []);
+
+            // ...
+        }
+    }
+
+Stored attributes remain in the session for the remainder of that user's session.
+
+.. tip::
+
+    Every ``SessionInterface`` implementation is supported. If you have your
+    own implementation, type-hint this in the argument instead.
+
+.. _session-avoid-start:
+
+Avoid Starting Sessions for Anonymous Users
+-------------------------------------------
+
+Sessions are automatically started whenever you read, write or even check for
+the existence of data in the session. This may hurt your application performance
+because all users will receive a session cookie. In order to prevent that, you
+must *completely* avoid accessing the session.
+
+For example, if your templates include some code to display the
+:ref:`flash messages <flash-messages>`, sessions will start even if the user
+is not logged in and even if you haven't created any flash messages. To avoid
+this behavior, add a check before trying to access the flash messages:
+
+.. code-block:: html+twig
+
+    {# this check prevents starting a session when there are no flash messages #}
+    {% if app.request.hasPreviousSession %}
+        {% for message in app.flashes('notice') %}
+            <div class="flash-notice">
+                {{ message }}
+            </div>
+        {% endfor %}
+    {% endif %}
 
 More about Sessions
 -------------------
 
 .. toctree::
     :maxdepth: 1
 
-    session/sessions_directory
-    session/avoid_session_start
+    /doctrine/pdo_session_storage
     session/locale_sticky_session
     session/php_bridge
     session/proxy_examples
 
-* :doc:`/doctrine/pdo_session_storage`
+.. _`HttpFoundation component`: https://symfony.com/components/HttpFoundation