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 3 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
99 changes: 50 additions & 49 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,50 @@ 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.

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 +219,22 @@ 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 ``/``)::
structure like this using a namespace character (which 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.

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

:method:`Symfony\\Component\\HttpFoundation\\Session\\Attribute\\AttributeBagInterface::clear`
Clear the bag.
To activate namespaced attributes, add this to your ``services.yml``::

# app/config/services.yml
services:
session:
class: Symfony\Component\HttpFoundation\Session\Session
arguments:
- @session.storage
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

shouldn't it be @session.storage.native?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@HeahDude you approved this PR ... but I'd like to ask you what do you think about this comment from @mhabibi. Do you agree with it? Thanks!

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We don't care about the implementation here, so we don't need to be specific in that case and the alias is used. From Symfony 3.3, it should SessionStorageInterface instead (autowired by default). See https://github.com/symfony/symfony/blob/master/src/Symfony/Bundle/FrameworkBundle/Resources/config/session.xml#L21, that keeps BC with the old alias.
We can merge as is, thanks!

- @app.session.attribute_bag # this service id is defined below
- @session.flash_bag
app.session.attribute_bag:
class: Symfony\Component\HttpFoundation\Session\Attribute\NamespacedAttributeBag

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