From 9a3b12f152340354aa3b5df2c51cee4e14abd08f Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Thu, 6 Mar 2014 13:22:59 +0100 Subject: [PATCH 1/2] Fixed some typos and formatting issues --- .../http_foundation/session_configuration.rst | 42 ++++++++++--------- components/http_foundation/sessions.rst | 14 +++---- 2 files changed, 29 insertions(+), 27 deletions(-) diff --git a/components/http_foundation/session_configuration.rst b/components/http_foundation/session_configuration.rst index f5ad863a2cb..bb8ba19c64e 100644 --- a/components/http_foundation/session_configuration.rst +++ b/components/http_foundation/session_configuration.rst @@ -13,16 +13,16 @@ Save Handlers ~~~~~~~~~~~~~ The PHP session workflow has 6 possible operations that may occur. The normal -session follows `open`, `read`, `write` and `close`, with the possibility of -`destroy` and `gc` (garbage collection which will expire any old sessions: `gc` -is called randomly according to PHP's configuration and if called, it is invoked -after the `open` operation). You can read more about this at +session follows ``open``, ``read``, ``write`` and ``close``, with the possibility +of ``destroy`` and ``gc`` (garbage collection which will expire any old sessions: +``gc`` is called randomly according to PHP's configuration and if called, it is +invoked after the ``open`` operation). You can read more about this at `php.net/session.customhandler`_ Native PHP Save Handlers ------------------------ -So-called 'native' handlers, are save handlers which are either compiled into +So-called *native* handlers, are save handlers which are either compiled into PHP or provided by PHP extensions, such as PHP-Sqlite, PHP-Memcached and so on. All native save handlers are internal to PHP and as such, have no public facing API. @@ -50,14 +50,16 @@ Example usage:: .. note:: - With the exception of the ``files`` handler which is built into PHP and always available, - the availability of the other handlers depends on those PHP extensions being active at runtime. + With the exception of the ``files`` handler which is built into PHP and + always available, the availability of the other handlers depends on those + PHP extensions being active at runtime. .. note:: - Native save handlers provide a quick solution to session storage, however, in complex systems - where you need more control, custom save handlers may provide more freedom and flexibility. - Symfony2 provides several implementations which you may further customize as required. + Native save handlers provide a quick solution to session storage, however, + in complex systems where you need more control, custom save handlers may + provide more freedom and flexibility. Symfony2 provides several implementations + which you may further customize as required. Custom Save Handlers -------------------- @@ -183,14 +185,14 @@ session is started. The session can be destroyed as required. This method of processing can allow the expiry of sessions to be integrated into the user experience, for example, by displaying a message. -Symfony2 records some basic meta-data about each session to give you complete +Symfony2 records some basic metadata about each session to give you complete freedom in this area. -Session meta-data -~~~~~~~~~~~~~~~~~ +Session metadata +~~~~~~~~~~~~~~~~ -Sessions are decorated with some basic meta-data to enable fine control over the -security settings. The session object has a getter for the meta-data, +Sessions are decorated with some basic metadata to enable fine control over the +security settings. The session object has a getter for the metadata, :method:`Symfony\\Component\\HttpFoundation\\Session\\Session::getMetadataBag` which exposes an instance of :class:`Symfony\\Component\\HttpFoundation\\Session\\Storage\\MetadataBag`:: @@ -199,7 +201,7 @@ exposes an instance of :class:`Symfony\\Component\\HttpFoundation\\Session\\Stor Both methods return a Unix timestamp (relative to the server). -This meta-data can be used to explicitly expire a session on access, e.g.:: +This metadata can be used to explicitly expire a session on access, e.g.:: $session->start(); if (time() - $session->getMetadataBag()->getLastUsed() > $maxIdleTime) { @@ -220,7 +222,7 @@ PHP 5.4 compatibility Since PHP 5.4.0, :phpclass:`SessionHandler` and :phpclass:`SessionHandlerInterface` are available. Symfony provides forward compatibility for the :phpclass:`SessionHandlerInterface` -so it can be used under PHP 5.3. This greatly improves inter-operability with other +so it can be used under PHP 5.3. This greatly improves interoperability with other libraries. :phpclass:`SessionHandler` is a special PHP internal class which exposes native save @@ -228,7 +230,7 @@ handlers to PHP user-space. In order to provide a solution for those using PHP 5.4, Symfony2 has a special class called :class:`Symfony\\Component\\HttpFoundation\\Session\\Storage\\Handler\\NativeSessionHandler` -which under PHP 5.4, extends from `\SessionHandler` and under PHP 5.3 is just a +which under PHP 5.4, extends from ``\SessionHandler`` and under PHP 5.3 is just a empty base class. This provides some interesting opportunities to leverage PHP 5.4 functionality if it is available. @@ -251,12 +253,12 @@ wrapped by one. :class:`Symfony\\Component\\HttpFoundation\\Session\\Storage\\Handler\\NativeProxy` is used automatically under PHP 5.3 when internal PHP save handlers are specified -using the `Native*SessionHandler` classes, while +using the ``Native*SessionHandler`` classes, while :class:`Symfony\\Component\\HttpFoundation\\Session\\Storage\\Handler\\SessionHandlerProxy` will be used to wrap any custom save handlers, that implement :phpclass:`SessionHandlerInterface`. From PHP 5.4 and above, all session handlers implement :phpclass:`SessionHandlerInterface` -including `Native*SessionHandler` classes which inherit from :phpclass:`SessionHandler`. +including ``Native*SessionHandler`` classes which inherit from :phpclass:`SessionHandler`. The proxy mechanism allows you to get more deeply involved in session save handler classes. A proxy for example could be used to encrypt any session transaction diff --git a/components/http_foundation/sessions.rst b/components/http_foundation/sessions.rst index 837da929b41..2f1ef11579e 100644 --- a/components/http_foundation/sessions.rst +++ b/components/http_foundation/sessions.rst @@ -121,7 +121,7 @@ an array. A few methods exist for "Bag" management: Gets the :class:`Symfony\\Component\\HttpFoundation\\Session\\Flash\\FlashBagInterface`. This is just a shortcut for convenience. -Session meta-data +Session metadata * :method:`Symfony\\Component\\HttpFoundation\\Session\\Session::getMetadataBag`: Gets the :class:`Symfony\\Component\\HttpFoundation\\Session\\Storage\\MetadataBag` @@ -132,8 +132,8 @@ Session Data Management PHP's session management requires the use of the ``$_SESSION`` super-global, however, this interferes somewhat with code testability and encapsulation in a -OOP paradigm. To help overcome this, Symfony2 uses 'session bags' linked to the -session to encapsulate a specific dataset of 'attributes' or 'flash messages'. +OOP paradigm. To help overcome this, Symfony2 uses *session bags* linked to the +session to encapsulate a specific dataset of attributes or flash messages. This approach also mitigates namespace pollution within the ``$_SESSION`` super-global because each bag stores all its data under a unique namespace. @@ -141,7 +141,7 @@ This allows Symfony2 to peacefully co-exist with other applications or libraries that might use the ``$_SESSION`` super-global and all data remains completely compatible with Symfony2's session management. -Symfony2 provides 2 kinds of storage bags, with two separate implementations. +Symfony2 provides two kinds of storage bags, with two separate implementations. Everything is written against interfaces so you may extend or create your own bag types if necessary. @@ -172,11 +172,11 @@ 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. -Any plain `key => value` storage system is limited in the extent to which +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 -your application could operate without clashing. For example, `module1.foo` and -`module2.foo`. However, sometimes this is not very practical when the attributes +your application could operate without clashing. For example, ``module1.foo`` and +``module2.foo``. However, sometimes this is not very practical when the attributes data is an array, for example a set of tokens. In this case, managing the array becomes a burden because you have to retrieve the array then process it and store it again:: From ce6fc73aeb086d00031f979006fca25916ba52af Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Sat, 8 Mar 2014 12:17:10 +0100 Subject: [PATCH 2/2] Minor corrections --- components/http_foundation/session_configuration.rst | 2 +- components/http_foundation/sessions.rst | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/components/http_foundation/session_configuration.rst b/components/http_foundation/session_configuration.rst index bb8ba19c64e..ba8dfa80fd8 100644 --- a/components/http_foundation/session_configuration.rst +++ b/components/http_foundation/session_configuration.rst @@ -22,7 +22,7 @@ invoked after the ``open`` operation). You can read more about this at Native PHP Save Handlers ------------------------ -So-called *native* handlers, are save handlers which are either compiled into +So-called native handlers, are save handlers which are either compiled into PHP or provided by PHP extensions, such as PHP-Sqlite, PHP-Memcached and so on. All native save handlers are internal to PHP and as such, have no public facing API. diff --git a/components/http_foundation/sessions.rst b/components/http_foundation/sessions.rst index 2f1ef11579e..dd5ddfdba54 100644 --- a/components/http_foundation/sessions.rst +++ b/components/http_foundation/sessions.rst @@ -172,7 +172,7 @@ 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. -Any plain ``key => value`` storage system is limited in the extent to which +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 your application could operate without clashing. For example, ``module1.foo`` and