bug symfony#3423 [Session Configuration] add clarifying notes on session save handler proxies (cordoval)

weaverryan · weaverryan · commit 26a7b1b80aa6 · 2014-01-08T21:55:50.000-06:00
This PR was merged into the 2.3 branch. Discussion ---------- [Session Configuration] add clarifying notes on session save handler proxies | Q | A | | --- | --- | | Doc fix? | yes | | New docs? | no | | Applies to | 2.3+ | | Fixed tickets | symfony#2889 | | License | CC-ASA 3.0 Unported | Sent using [Gush](https://github.com/cordoval/gush) Commits ------- 771b862 address comments from @wouterj 2888d00 answer some questions and clarify the best chapter imo from the symfony documentation
diff --git a/components/http_foundation/session_configuration.rst b/components/http_foundation/session_configuration.rst
@@ -28,11 +28,12 @@ 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.
 They must be configured by ``php.ini`` directives, usually ``session.save_path`` and
 potentially other driver specific directives. Specific details can be found in
-docblock of the ``setOptions()`` method of each class.
+the docblock of the ``setOptions()`` method of each class. For instance, the one
+provided by the Memcached extension can be found on `php.net/memcached.setoption`_
 
 While native save handlers can be activated by directly using
 ``ini_set('session.save_handler', $name);``, Symfony2 provides a convenient way to
-activate these in the same way as custom handlers.
+activate these in the same way as it does for custom handlers.
 
 Symfony2 provides drivers for the following native save handler as an example:
 
@@ -61,7 +62,7 @@ Example usage::
 Custom Save Handlers
 --------------------
 
-Custom handlers are those which completely replace PHP's built in session save
+Custom handlers are those which completely replace PHP's built-in session save
 handlers by providing six callback functions which PHP calls internally at
 various points in the session workflow.
 
@@ -234,6 +235,11 @@ PHP 5.4 functionality if it is available.
 Save Handler Proxy
 ~~~~~~~~~~~~~~~~~~
 
+A Save Handler Proxy is basically a wrapper around a Save Handler that was
+introduced to support seamlessly the migration from PHP 5.3 to PHP 5.4+. It
+further creates an extension point from where custom logic can be added that
+works independently of which handler is being wrapped inside.
+
 There are two kinds of save handler class proxies which inherit from
 :class:`Symfony\\Component\\HttpFoundation\\Session\\Storage\\Handler\\AbstractProxy`:
 they are :class:`Symfony\\Component\\HttpFoundation\\Session\\Storage\\Handler\\NativeProxy`
@@ -263,3 +269,4 @@ without knowledge of the specific save handler.
 
 .. _`php.net/session.customhandler`: http://php.net/session.customhandler
 .. _`php.net/session.configuration`: http://php.net/session.configuration
+.. _`php.net/memcached.setoption`: http://php.net/memcached.setoption
