diff --git a/_build/redirection_map b/_build/redirection_map index a82a559aeeb..66e8aaab63a 100644 --- a/_build/redirection_map +++ b/_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 diff --git a/controller.rst b/controller.rst index d9a521a6e61..480c3216967 100644 --- a/controller.rst +++ b/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 ~~~~~~~~~~~~~~ diff --git a/http_cache/varnish.rst b/http_cache/varnish.rst index ae7a6395b70..4274fa6bbe1 100644 --- a/http_cache/varnish.rst +++ b/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 `. In this situation, make sure to -:doc:`only start a session when actually needed ` +:ref:`only start a session when actually needed ` and clear the session when it is no longer needed. Alternatively, you can look into :ref:`caching pages that contain CSRF protected forms `. diff --git a/reference/configuration/framework.rst b/reference/configuration/framework.rst index 83325d3e26d..7e1f0a8a589 100644 --- a/reference/configuration/framework.rst +++ b/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``: diff --git a/session.rst b/session.rst index a046cc47896..4b4be08a7b0 100644 --- a/session.rst +++ b/session.rst @@ -1,10 +1,139 @@ 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 + + + + + + + + + + + + .. 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 `. 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 `, 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') %} +
+ {{ message }} +
+ {% endfor %} + {% endif %} More about Sessions ------------------- @@ -12,10 +141,9 @@ 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 diff --git a/session/avoid_session_start.rst b/session/avoid_session_start.rst deleted file mode 100644 index e19498184cf..00000000000 --- a/session/avoid_session_start.rst +++ /dev/null @@ -1,38 +0,0 @@ -.. index:: - single: Sessions, cookies - -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 means that if you need to avoid creating -a session cookie for some users, it can be difficult: you must *completely* avoid -accessing the session. - -For example, one common problem in this situation involves checking for flash -messages, which are stored in the session. The following code would guarantee -that a session is *always* started: - -.. code-block:: html+twig - - {% for message in app.flashes('notice') %} -
- {{ message }} -
- {% endfor %} - -Even if the user is not logged in and even if you haven't created any flash messages, -just calling the ``get()`` (or even ``has()``) method of the ``flashBag`` will -start a session. This may hurt your application performance because all users will -receive a session cookie. To avoid this behavior, add a check before trying to -access the flash messages: - -.. code-block:: html+twig - - {% if app.request.hasPreviousSession %} - {% for message in app.flashes('notice') %} -
- {{ message }} -
- {% endfor %} - {% endif %} diff --git a/session/sessions_directory.rst b/session/sessions_directory.rst deleted file mode 100644 index b1f6eb364b7..00000000000 --- a/session/sessions_directory.rst +++ /dev/null @@ -1,54 +0,0 @@ -.. index:: - single: Sessions, sessions directory - -Configuring the Directory where Session Files are Saved -======================================================= - -By default, Symfony stores session metadata on the filesystem. If you want to control -this path, update the ``framework.session.save_path`` configuration key: - -.. 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 - - - - - - - - - - - .. code-block:: php - - // config/packages/framework.php - $container->loadFromExtension('framework', [ - 'session' => [ - 'handler_id' => 'session.handler.native_file', - 'save_path' => '%kernel.project_dir%/var/sessions/%kernel.environment%' - ], - ]); - -Storing Sessions Elsewhere (e.g. database) ------------------------------------------- - -You can store your session data anywhere by using the ``handler_id`` option. -See :doc:`/components/http_foundation/session_configuration` for a discussion of -session save handlers. There are also articles about storing sessions in a -:doc:`relational database ` -or a :doc:`NoSQL database `.