From 41080e0ad33f785dbf097e72770cb0086d539892 Mon Sep 17 00:00:00 2001 From: David Buchmann Date: Fri, 1 Jul 2016 14:00:12 +0200 Subject: [PATCH] clarify hash lookup can be anonymous --- doc/user-context.rst | 24 +++++++++++++++++++++--- 1 file changed, 21 insertions(+), 3 deletions(-) diff --git a/doc/user-context.rst b/doc/user-context.rst index 495e6fc7..492443f1 100644 --- a/doc/user-context.rst +++ b/doc/user-context.rst @@ -11,6 +11,10 @@ The FOSHttpCache library includes a solution to cache responses per user context (whether the user is authenticated, groups the user is in, or other information), rather than individually. +If every user has their own hash, you probably don't want to cache at all. Or +if you found out its worth it, vary on the credentials and don't use the +context hash mechanism. + .. caution:: Whenever you share caches, make sure to not output any individual content @@ -47,8 +51,22 @@ Currently, user context caching is only supported by Varnish and by the Symfony HttpCache. See the :ref:`Varnish Configuration ` or :ref:`Symfony HttpCache Configuration `. +User Context Hash from Your Application +--------------------------------------- + +It is your application's responsibility to determine the hash for a user. Only +your application can know what is relevant for the hash. You can use the path +or the accept header to detect that a hash was requested. + +.. warning:: + + Treat the hash lookup path like the login path so that anonymous users also + can get a hash. That means that your cache can access the hash lookup even + with no user provided credential and that the hash lookup never redirects + to a login page. + Calculating the User Context Hash ---------------------------------- +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The user context hash calculation (step 3 above) is managed by the HashGenerator. Because the calculation itself will be different per application, you need to @@ -65,7 +83,7 @@ Once all providers are registered, call ``generateHash()`` to get the hash for the current user context. Context Providers ------------------ +~~~~~~~~~~~~~~~~~ Each provider is passed the :source:`UserContext ` and updates that with parameters which influence the varied response. @@ -93,7 +111,7 @@ A provider that looks at whether the user is authenticated could look like this: .. _return context hash: Returning the User Context Hash -------------------------------- +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ It is up to you to return the user context hash in response to the hash request (``/_fos_user_context_hash`` in step 3 above)::