feature #4661 Added a short cookbook about avoiding the automatic start of the sessions (javiereguiluz)

weaverryan · weaverryan · commit 018cf3fc6558 · 2015-02-05T14:25:45.000-05:00
This PR was merged into the 2.3 branch. Discussion ---------- Added a short cookbook about avoiding the automatic start of the sessions | Q | A | ------------- | --- | Doc fix? | no | New docs? | yes | Applies to | all | Fixed tickets | #2607 Besides all the usual review, I'd like to ask doc reviewers to tell me if there is some way to avoid starting the session in the last case about defining a firewall that covers all URLs. Thanks in advance! Commits ------- bbba47a Added all sugestions made by reviewers 7dd3945 Added the new cookbook article to the global map 0212779 Tweaks and rewordings to improve the article 99781f8 Added a short cookbook about avoiding the automatic start of the sessions
diff --git a/cookbook/map.rst.inc b/cookbook/map.rst.inc
@@ -175,6 +175,7 @@
   * :doc:`/cookbook/session/sessions_directory`
   * :doc:`/cookbook/session/php_bridge`
   * (configuration) :doc:`/cookbook/configuration/pdo_session_storage`
+  * :doc:`/cookbook/session/avoid_session_start`
 
 * **symfony1**
 
diff --git a/cookbook/session/avoid_session_start.rst b/cookbook/session/avoid_session_start.rst
@@ -0,0 +1,38 @@
+.. 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+jinja
+
+    {% for flashMessage in app.session.flashbag.get('notice') %}
+        <div class="flash-notice">
+            {{ flashMessage }}
+        </div>
+    {% endfor %}
+
+Even if the user is not logged in and even if you haven't created any flash message,
+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+jinja
+
+    {% if app.request.hasPreviousSession %}
+        {% for flashMessage in app.session.flashbag.get('notice') %}
+            <div class="flash-notice">
+                {{ flashMessage }}
+            </div>
+        {% endfor %}
+    {% endif %}
diff --git a/cookbook/session/index.rst b/cookbook/session/index.rst
@@ -7,4 +7,5 @@ Sessions
     proxy_examples
     locale_sticky_session
     sessions_directory
-    php_bridge
+    php_bridge
+    avoid_session_start
