Skip to content

Update sessions.rst #7643

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

Closed
wants to merge 4 commits into from
Closed

Update sessions.rst #7643

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
a1504f0
Update sessions.rst
ThomasLandauer Mar 16, 2017
269e3c6
Removed some repeated content and minor rewords
javiereguiluz Mar 17, 2017
1070050
Update sessions.rst
ThomasLandauer Mar 27, 2017
0648be0
Reword and simplify
javiereguiluz Jul 24, 2018
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
107 changes: 57 additions & 50 deletions components/http_foundation/sessions.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -94,29 +94,12 @@ Session Workflow
Session Attributes
..................

:method:`Symfony\\Component\\HttpFoundation\\Session\\Session::set`
Sets an attribute by key.
The session attributes are stored internally in a "Bag", a PHP object that acts
like an array. They can be set, removed, checked, etc. using the methods
explained later in this article for the ``AttributeBagInterface`` class. See
:ref:`attribute-bag-interface`.

:method:`Symfony\\Component\\HttpFoundation\\Session\\Session::get`
Gets an attribute by key.

:method:`Symfony\\Component\\HttpFoundation\\Session\\Session::all`
Gets all attributes as an array of key => value.

:method:`Symfony\\Component\\HttpFoundation\\Session\\Session::has`
Returns true if the attribute exists.

:method:`Symfony\\Component\\HttpFoundation\\Session\\Session::replace`
Sets multiple attributes at once: takes a keyed array and sets each key => value pair.

:method:`Symfony\\Component\\HttpFoundation\\Session\\Session::remove`
Deletes an attribute by key.

:method:`Symfony\\Component\\HttpFoundation\\Session\\Session::clear`
Clear all attributes.

The attributes are stored internally in a "Bag", a PHP object that acts like
an array. A few methods exist for "Bag" management:
In addition, a few methods exist for "Bag" management:

:method:`Symfony\\Component\\HttpFoundation\\Session\\Session::registerBag`
Registers a :class:`Symfony\\Component\\HttpFoundation\\Session\\SessionBagInterface`.
Expand Down Expand Up @@ -168,19 +151,65 @@ the following API which is intended mainly for internal purposes:
:method:`Symfony\\Component\\HttpFoundation\\Session\\SessionBagInterface::getName`
Returns the name of the session bag.

.. _attribute-bag-interface:

Attributes
~~~~~~~~~~

The purpose of the bags implementing the :class:`Symfony\\Component\\HttpFoundation\\Session\\Attribute\\AttributeBagInterface`
is to handle session attribute storage. This might include things like user ID,
and remember me login settings or other user based state information.
and "Remember Me" login settings or other user based state information.

:class:`Symfony\\Component\\HttpFoundation\\Session\\Attribute\\AttributeBag`
This is the standard default implementation.

:class:`Symfony\\Component\\HttpFoundation\\Session\\Attribute\\NamespacedAttributeBag`
This implementation allows for attributes to be stored in a structured namespace.

:class:`Symfony\\Component\\HttpFoundation\\Session\\Attribute\\AttributeBagInterface`
has a simple API

:method:`Symfony\\Component\\HttpFoundation\\Session\\Attribute\\AttributeBagInterface::set`
Sets an attribute by name (``set('name', 'value')``).

:method:`Symfony\\Component\\HttpFoundation\\Session\\Attribute\\AttributeBagInterface::get`
Gets an attribute by name (``get('name')``) and can define a default
value when the attribute doesn't exist (``get('name', 'default_value')``).

:method:`Symfony\\Component\\HttpFoundation\\Session\\Attribute\\AttributeBagInterface::all`
Gets all attributes as an associative array of ``name => value``.

:method:`Symfony\\Component\\HttpFoundation\\Session\\Attribute\\AttributeBagInterface::has`
Returns ``true`` if the attribute exists.

:method:`Symfony\\Component\\HttpFoundation\\Session\\Attribute\\AttributeBagInterface::replace`
Sets multiple attributes at once using an associative array (``name => value``).
If the attributes existed, they are replaced; if not, they are created.

:method:`Symfony\\Component\\HttpFoundation\\Session\\Attribute\\AttributeBagInterface::remove`
Deletes an attribute by name and returns its value.

:method:`Symfony\\Component\\HttpFoundation\\Session\\Attribute\\AttributeBagInterface::clear`
Deletes all attributes.

Example::

use Symfony\Component\HttpFoundation\Session\Attribute\AttributeBag;
use Symfony\Component\HttpFoundation\Session\Session;
use Symfony\Component\HttpFoundation\Session\Storage\NativeSessionStorage;

$session = new Session(new NativeSessionStorage(), new AttributeBag());
$session->set('token', 'a6c1e0b6');
// ...
$token = $session->get('token');
// if the attribute may or may not exist, you can define a default value for it
$token = $session->get('attribute-name', 'default-attribute-value');
// ...
$session->clear();

Namespaced Attributes
.....................

Any plain key-value storage system is limited in the extent to which
complex data can be stored since each key must be unique. You can achieve
namespacing by introducing a naming convention to the keys so different parts of
Expand All @@ -205,35 +234,13 @@ the array::
$session->set('tokens', $tokens);

With structured namespacing, the key can be translated to the array
structure like this using a namespace character (defaults to ``/``)::

$session->set('tokens/c', $value);

This way you can easily access a key within the stored array directly and easily.

:class:`Symfony\\Component\\HttpFoundation\\Session\\Attribute\\AttributeBagInterface`
has a simple API

:method:`Symfony\\Component\\HttpFoundation\\Session\\Attribute\\AttributeBagInterface::set`
Sets an attribute by key.

:method:`Symfony\\Component\\HttpFoundation\\Session\\Attribute\\AttributeBagInterface::get`
Gets an attribute by key.

:method:`Symfony\\Component\\HttpFoundation\\Session\\Attribute\\AttributeBagInterface::all`
Gets all attributes as an array of key => value.

:method:`Symfony\\Component\\HttpFoundation\\Session\\Attribute\\AttributeBagInterface::has`
Returns true if the attribute exists.

:method:`Symfony\\Component\\HttpFoundation\\Session\\Attribute\\AttributeBagInterface::replace`
Sets multiple attributes at once: takes a keyed array and sets each key => value pair.
structure like this using a namespace character (which defaults to ``/``)::

:method:`Symfony\\Component\\HttpFoundation\\Session\\Attribute\\AttributeBagInterface::remove`
Deletes an attribute by key.
// ...
use Symfony\Component\HttpFoundation\Session\Attribute\NamespacedAttributeBag;

:method:`Symfony\\Component\\HttpFoundation\\Session\\Attribute\\AttributeBagInterface::clear`
Clear the bag.
$session = new Session(new NativeSessionStorage(), new NamespacedAttributeBag());
$session->set('tokens/c', $value);

Flash Messages
~~~~~~~~~~~~~~
Expand Down