Skip to content

clarify hash lookup can be anonymous #292

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Jul 1, 2016
Merged

clarify hash lookup can be anonymous #292

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
24 changes: 21 additions & 3 deletions doc/user-context.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -47,8 +51,22 @@ Currently, user context caching is only supported by Varnish and by the Symfony
HttpCache. See the :ref:`Varnish Configuration <varnish user context>` or
:ref:`Symfony HttpCache Configuration <symfony-cache user context>`.

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
Expand All @@ -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 <src/UserContext/UserContext.php>`
and updates that with parameters which influence the varied response.
Expand Down Expand Up @@ -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)::
Expand Down