From a1504f06f453df628376cdf242214e857f8ccfce Mon Sep 17 00:00:00 2001 From: Thomas Landauer Date: Thu, 16 Mar 2017 23:41:07 +0100 Subject: [PATCH 1/4] Update sessions.rst First step to explain how to activate Namespaced Attributes, as requested by https://github.com/symfony/symfony-docs/issues/7378 --- components/http_foundation/sessions.rst | 63 ++++++++++++++++--------- 1 file changed, 40 insertions(+), 23 deletions(-) diff --git a/components/http_foundation/sessions.rst b/components/http_foundation/sessions.rst index 60b639c8dd9..1adb2b7def9 100644 --- a/components/http_foundation/sessions.rst +++ b/components/http_foundation/sessions.rst @@ -181,6 +181,33 @@ and remember me login settings or other user based state information. :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 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. + +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 @@ -211,29 +238,19 @@ structure like this using a namespace character (defaults to ``/``):: 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 + - @your.session.attribute_bag #service id is defined below + - @session.flash_bag + your.session.attribute_bag: + class: Symfony\Component\HttpFoundation\Session\Attribute\NamespacedAttributeBag Flash Messages ~~~~~~~~~~~~~~ From 269e3c6eb5d0316969efabd0d0282a628962cd87 Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Fri, 17 Mar 2017 08:39:52 +0100 Subject: [PATCH 2/4] Removed some repeated content and minor rewords --- components/http_foundation/sessions.rst | 58 +++++++++---------------- 1 file changed, 21 insertions(+), 37 deletions(-) diff --git a/components/http_foundation/sessions.rst b/components/http_foundation/sessions.rst index 1adb2b7def9..b00bf1e4b99 100644 --- a/components/http_foundation/sessions.rst +++ b/components/http_foundation/sessions.rst @@ -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`. @@ -168,12 +151,14 @@ 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. @@ -185,25 +170,27 @@ and remember me login settings or other user based state information. has a simple API :method:`Symfony\\Component\\HttpFoundation\\Session\\Attribute\\AttributeBagInterface::set` - Sets an attribute by key. + Sets an attribute by name (``set('name', 'value')``). :method:`Symfony\\Component\\HttpFoundation\\Session\\Attribute\\AttributeBagInterface::get` - Gets an attribute by key. + 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 array of key => value. + Gets all attributes as an associative array of ``name => value``. :method:`Symfony\\Component\\HttpFoundation\\Session\\Attribute\\AttributeBagInterface::has` - Returns true if the attribute exists. + 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. + 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 key. + Deletes an attribute by name. :method:`Symfony\\Component\\HttpFoundation\\Session\\Attribute\\AttributeBagInterface::clear` - Clear the bag. + Deletes all attributes. Namespaced Attributes ..................... @@ -232,24 +219,21 @@ 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. - -To activate Namespaced Attributes, add this to your `services.yml`:: +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 - - @your.session.attribute_bag #service id is defined below + - @app.session.attribute_bag # this service id is defined below - @session.flash_bag - your.session.attribute_bag: + app.session.attribute_bag: class: Symfony\Component\HttpFoundation\Session\Attribute\NamespacedAttributeBag Flash Messages From 107005035d92fa39431a720046beeb54e323cb88 Mon Sep 17 00:00:00 2001 From: Thomas Landauer Date: Mon, 27 Mar 2017 13:45:23 +0200 Subject: [PATCH 3/4] Update sessions.rst As requested here :-) https://github.com/symfony/symfony-docs/pull/7643#pullrequestreview-29070751 --- components/http_foundation/sessions.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/components/http_foundation/sessions.rst b/components/http_foundation/sessions.rst index b00bf1e4b99..aace98db979 100644 --- a/components/http_foundation/sessions.rst +++ b/components/http_foundation/sessions.rst @@ -187,7 +187,7 @@ has a simple API 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. + Deletes an attribute by name and returns its value. :method:`Symfony\\Component\\HttpFoundation\\Session\\Attribute\\AttributeBagInterface::clear` Deletes all attributes. From 0648be037376550c11572383e8600f7b9b5320c8 Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Tue, 24 Jul 2018 15:42:34 +0200 Subject: [PATCH 4/4] Reword and simplify --- components/http_foundation/sessions.rst | 32 +++++++++++++++---------- 1 file changed, 19 insertions(+), 13 deletions(-) diff --git a/components/http_foundation/sessions.rst b/components/http_foundation/sessions.rst index aace98db979..609bee58191 100644 --- a/components/http_foundation/sessions.rst +++ b/components/http_foundation/sessions.rst @@ -192,6 +192,21 @@ has a simple API :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 ..................... @@ -221,20 +236,11 @@ the array:: With structured namespacing, the key can be translated to the array structure like this using a namespace character (which defaults to ``/``):: - $session->set('tokens/c', $value); + // ... + use Symfony\Component\HttpFoundation\Session\Attribute\NamespacedAttributeBag; -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 - - @app.session.attribute_bag # this service id is defined below - - @session.flash_bag - app.session.attribute_bag: - class: Symfony\Component\HttpFoundation\Session\Attribute\NamespacedAttributeBag + $session = new Session(new NativeSessionStorage(), new NamespacedAttributeBag()); + $session->set('tokens/c', $value); Flash Messages ~~~~~~~~~~~~~~