-

Author: fabpot

controller.rst

@@ -394,6 +394,40 @@ Request object.
 Managing the Session
 --------------------
 
+You can store special messages, called "flash" messages, on the user's session.
+By design, flash messages are meant to be used exactly once: they vanish from
+the session automatically as soon as you retrieve them. This feature makes
+"flash" messages particularly great for storing user notifications.
+
+For example, imagine you're processing a :doc:`form </forms>` submission::
+
+.. configuration-block::
+
+    .. code-block:: php-symfony
+
+        use Symfony\Component\HttpFoundation\Request;
+        use Symfony\Component\HttpFoundation\Response;
+        // ...
+
+        public function update(Request $request): Response
+        {
+            // ...
+
+            if ($form->isSubmitted() && $form->isValid()) {
+                // do some sort of processing
+
+                $this->addFlash(
+                    'notice',
+                    'Your changes were saved!'
+                );
+                // $this->addFlash() is equivalent to $request->getSession()->getFlashBag()->add()
+
+                return $this->redirectToRoute(/* ... */);
+            }
+
+            return $this->render(/* ... */);
+        }
+
 :ref:`Reading <session-intro>` for more information about using Sessions.
 
 .. index::

session.rst

@@ -66,16 +66,11 @@ if you type-hint an argument with :class:`Symfony\\Component\\HttpFoundation\\Re
 
     .. code-block:: php-standalone
 
-        use Symfony\Component\HttpFoundation\Session\Attribute\AttributeBag;
         use Symfony\Component\HttpFoundation\Session\Session;
-        use Symfony\Component\HttpFoundation\Session\Storage\NativeSessionStorage;
 
         $session = new Session();
         $session->start();
 
-        // Pass a storage and a bag implementation explicitely
-        $session = new Session(new NativeSessionStorage(), new AttributeBag());
-
 From a Symfony controller, type-hint an argument with
 :class:`Symfony\\Component\\HttpFoundation\\RequestStack` or
 :class:`Symfony\\Component\\HttpFoundation\\Request`::
@@ -336,6 +331,19 @@ configuration <config-framework-session>` in
             ;
         };
 
+    .. code-block:: php-standalone
+
+        use Symfony\Component\HttpFoundation\Cookie;
+        use Symfony\Component\HttpFoundation\Session\Attribute\AttributeBag;
+        use Symfony\Component\HttpFoundation\Session\Session;
+        use Symfony\Component\HttpFoundation\Session\Storage\NativeSessionStorage;
+
+        $storage = new NativeSessionStorage([
+            'cookie_secure' => 'auto',
+            'cookie_samesite' => Cookie::SAMESITE_LAX,
+        ]);
+        $session = new Session($storage);
+
 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
@@ -390,6 +398,18 @@ session metadata files:
             ;
         };
 
+    .. code-block:: php-standalone
+
+        use Symfony\Component\HttpFoundation\Cookie;
+        use Symfony\Component\HttpFoundation\Session\Attribute\AttributeBag;
+        use Symfony\Component\HttpFoundation\Session\Session;
+        use Symfony\Component\HttpFoundation\Session\Storage\Handler\NativeFileSessionHandler;
+        use Symfony\Component\HttpFoundation\Session\Storage\NativeSessionStorage;
+
+        $handler = new NativeFileSessionHandler('/var/sessions');
+        $storage = new NativeSessionStorage([], $handler);
+        $session = new Session($storage);
+
 Check out the Symfony config reference to learn more about the other available
 :ref:`Session configuration options <config-framework-session>`.