Skip to content
This repository
Browse code

merged branch drak/session_docblocks (PR #3413)

Commits
-------

09be5cb [HttpFoundation] Documentation.
7f8c293 [HttpFoudation] Add ability to configure sqlite session storage.

Discussion
----------

[HttpFoundation] Session docblocks

Bug fix: no
Feature addition: no
Backwards compatibility break: no
Symfony2 tests pass: yes
Fixes the following tickets: -
Todo: -

---------------------------------------------------------------------------

by drak at 2012-02-22T18:19:45Z

Please note the documentation referred to will be published a php.net this Friday (docs are built weekly).

---------------------------------------------------------------------------

by drak at 2012-02-24T11:16:57Z

@fabpot - this is ready for merge.

---------------------------------------------------------------------------

by fabpot at 2012-03-01T00:02:09Z

Can you squash your commits before I merge? Thanks.

---------------------------------------------------------------------------

by drak at 2012-03-01T00:57:50Z

Done.
  • Loading branch information...
commit 828003313eb4025b25c9c8205c4a99b21aab6f0f 2 parents 4c1cea7 + 09be5cb
Fabien Potencier authored March 01, 2012
81  src/Symfony/Component/HttpFoundation/Resources/stubs/SessionHandlerInterface.php
@@ -10,43 +10,15 @@
10 10
  */
11 11
 
12 12
 /**
13  
- * Session Savehandler Interface.
  13
+ * SessionHandlerInterface
14 14
  *
15  
- * This interface is for implementing methods required for the
16  
- * session_set_save_handler() function.
  15
+ * Provides forward compatability with PHP 5.4
17 16
  *
18  
- * @see http://php.net/session_set_save_handler
  17
+ * Extensive documentation can be found at php.net, see links:
19 18
  *
20  
- * These are methods called by PHP when the session is started
21  
- * and closed and for various house-keeping tasks required
22  
- * by session management.
23  
- *
24  
- * PHP requires session save handlers. There are some defaults set
25  
- * automatically when PHP starts, but these can be overriden using
26  
- * this command if you need anything other than PHP's default handling.
27  
- *
28  
- * When the session starts, PHP will call the read() handler
29  
- * which should return a string extactly as stored (which will have
30  
- * been encoded by PHP using a special session serializer session_decode()
31  
- * which is different to the serialize() function. PHP will then populate
32  
- * these into $_SESSION.
33  
- *
34  
- * When PHP shuts down, the write() handler is called and will pass
35  
- * the $_SESSION contents already serialized (using session_encode()) to
36  
- * be stored.
37  
- *
38  
- * When a session is specifically destroyed, PHP will call the
39  
- * destroy() handler with the session ID. This happens when the
40  
- * session is regenerated for example and th handler MUST delete the
41  
- * session by ID from the persistent storage immediately.
42  
- *
43  
- * PHP will call gc() from time to time to expire any session
44  
- * records according to the set max lifetime of a session. This routine
45  
- * should delete all records from persistent storage which were last
46  
- * accessed longer than the $lifetime.
47  
- *
48  
- * PHP open() and close() are pretty much redundant and
49  
- * can return true.
  19
+ * @see http://php.net/sessionhandlerinterface
  20
+ * @see http://php.net/session.customhandler
  21
+ * @see http://php.net/session-set-save-handler
50 22
  *
51 23
  * @author Drak <drak@zikula.org>
52 24
  */
@@ -55,7 +27,7 @@
55 27
     /**
56 28
      * Open session.
57 29
      *
58  
-     * This method is for internal use by PHP and must not be called manually.
  30
+     * @see http://php.net/sessionhandlerinterface.open
59 31
      *
60 32
      * @param string $savePath    Save path.
61 33
      * @param string $sessionName Session Name.
@@ -69,7 +41,7 @@ function open($savePath, $sessionName);
69 41
     /**
70 42
      * Close session.
71 43
      *
72  
-     * This method is for internal use by PHP and must not be called manually.
  44
+     * @see http://php.net/sessionhandlerinterface.close
73 45
      *
74 46
      * @return boolean
75 47
      */
@@ -78,19 +50,7 @@ function close();
78 50
     /**
79 51
      * Read session.
80 52
      *
81  
-     * This method is for internal use by PHP and must not be called manually.
82  
-     *
83  
-     * This method is called by PHP itself when the session is started.
84  
-     * This method should retrieve the session data from storage by the
85  
-     * ID provided by PHP. Return the string directly as is from storage.
86  
-     * If the record was not found you must return an empty string.
87  
-     *
88  
-     * The returned data will be unserialized automatically by PHP using a
89  
-     * special unserializer method session_decode() and the result will be used
90  
-     * to populate the $_SESSION superglobal. This is done automatically and
91  
-     * is not configurable.
92  
-     *
93  
-     * @param string $sessionId Session ID.
  53
+     * @see http://php.net/sessionhandlerinterface.read
94 54
      *
95 55
      * @throws \RuntimeException On fatal error but not "record not found".
96 56
      *
@@ -101,21 +61,11 @@ function read($sessionId);
101 61
     /**
102 62
      * Commit session to storage.
103 63
      *
104  
-     * This method is for internal use by PHP and must not be called manually.
105  
-     *
106  
-     * PHP will call this method when the session is closed. It sends
107  
-     * the session ID and the contents of $_SESSION to be saved in a lightweight
108  
-     * serialized format (which PHP does automatically using session_encode()
109  
-     * which should be stored exactly as is given in $data.
110  
-     *
111  
-     * Note this method is normally called by PHP after the output buffers
112  
-     * have been closed.
  64
+     * @see http://php.net/sessionhandlerinterface.write
113 65
      *
114 66
      * @param string $sessionId Session ID.
115 67
      * @param string $data      Session serialized data to save.
116 68
      *
117  
-     * @throws \RuntimeException On fatal error.
118  
-     *
119 69
      * @return boolean
120 70
      */
121 71
     function write($sessionId, $data);
@@ -123,11 +73,7 @@ function write($sessionId, $data);
123 73
     /**
124 74
      * Destroys this session.
125 75
      *
126  
-     * This method is for internal use by PHP and must not be called manually.
127  
-     *
128  
-     * PHP will call this method when the session data associated
129  
-     * with the session ID provided needs to be immediately
130  
-     * deleted from the permanent storage.
  76
+     * @see http://php.net/sessionhandlerinterface.destroy
131 77
      *
132 78
      * @param string $sessionId Session ID.
133 79
      *
@@ -140,10 +86,7 @@ function destroy($sessionId);
140 86
     /**
141 87
      * Garbage collection for storage.
142 88
      *
143  
-     * This method is for internal use by PHP and must not be called manually.
144  
-     *
145  
-     * This method is called by PHP periodically and passes the maximum
146  
-     * time a session can exist for before being deleted from permanent storage.
  89
+     * @see http://php.net/sessionhandlerinterface.gc
147 90
      *
148 91
      * @param integer $lifetime Max lifetime in seconds to keep sessions stored.
149 92
      *
54  src/Symfony/Component/HttpFoundation/Session/Storage/AbstractSessionStorage.php
@@ -16,6 +16,13 @@
16 16
 /**
17 17
  * This provides a base class for session attribute storage.
18 18
  *
  19
+ * This can be used to implement internal PHP session handlers
  20
+ * provided by PHP extensions or custom session save handlers
  21
+ * implementing the \SessionHandlerInterface
  22
+ *
  23
+ * @see http://php.net/session.customhandler
  24
+ * @see http://php.net/sessionhandlerinterface
  25
+ *
19 26
  * @author Drak <drak@zikula.org>
20 27
  */
21 28
 abstract class AbstractSessionStorage implements SessionStorageInterface
@@ -49,11 +56,11 @@
49 56
      * want top override this constructor entirely.
50 57
      *
51 58
      * List of options for $options array with their defaults.
52  
-     * @see http://www.php.net/manual/en/session.configuration.php for options
53  
-     * but we omit 'session.' from the beginning of the keys.
  59
+     * @see http://php.net/session.configuration for options
  60
+     * but we omit 'session.' from the beginning of the keys for convenience.
54 61
      *
55 62
      * auto_start, "0"
56  
-     * cache_limiter, ""
  63
+     * cache_limiter, "nocache" (use "0" to prevent headers from being sent entirely).
57 64
      * cookie_domain, ""
58 65
      * cookie_httponly, ""
59 66
      * cookie_lifetime, "0"
@@ -81,7 +88,7 @@
81 88
      * upload_progress.min-freq, "1"
82 89
      * url_rewriter.tags, "a=href,area=href,frame=src,form=,fieldset="
83 90
      *
84  
-     * @param array                 $options    Session configuration options.
  91
+     * @param array $options Session configuration options.
85 92
      */
86 93
     public function __construct(array $options = array())
87 94
     {
@@ -196,7 +203,7 @@ public function getBag($name)
196 203
      *
197 204
      * @param array $options
198 205
      *
199  
-     * @see http://www.php.net/manual/en/session.configuration.php
  206
+     * @see http://php.net/session.configuration
200 207
      */
201 208
     protected function setOptions(array $options)
202 209
     {
@@ -240,39 +247,16 @@ protected function setOptions(array $options)
240 247
     }
241 248
 
242 249
     /**
243  
-     * Registers this storage device for PHP session handling.
244  
-     *
245  
-     * PHP requires session save handlers to be set, either it's own, or custom ones.
246  
-     * There are some defaults set automatically when PHP starts, but these can be overriden
247  
-     * using this command if you need anything other than PHP's default handling.
248  
-     *
249  
-     * When the session starts, PHP will call the sessionRead() handler which should return an array
250  
-     * of any session attributes. PHP will then populate these into $_SESSION.
251  
-     *
252  
-     * When PHP shuts down, the write() handler is called and will pass the $_SESSION contents
253  
-     * to be stored.
  250
+     * Registers this storage device as a PHP session handler.
254 251
      *
255  
-     * When a session is specifically destroyed, PHP will call the destroy() handler with the
256  
-     * session ID. This happens when the session is regenerated for example and th handler
257  
-     * MUST delete the session by ID from the persistent storage immediately.
258  
-     *
259  
-     * PHP will call gc() from time to time to expire any session records according to the
260  
-     * set max lifetime of a session. This routine should delete all records from persistent
261  
-     * storage which were last accessed longer than the $lifetime.
262  
-     *
263  
-     * PHP open() and close() are pretty much redundant and can just return true.
264  
-     *
265  
-     * NOTE:
266  
-     *
267  
-     * To use PHP native save handlers, override this method using ini_set with
  252
+     * To use internal PHP session save handlers, override this method using ini_set with
268 253
      * session.save_handlers and session.save_path e.g.
269 254
      *
270 255
      *     ini_set('session.save_handlers', 'files');
271 256
      *     ini_set('session.save_path', /tmp');
272 257
      *
273  
-     * @see http://php.net/manual/en/function.session-set-save-handler.php
274  
-     * @see \SessionHandlerInterface
275  
-     * @see http://php.net/manual/en/class.sessionhandlerinterface.php
  258
+     * @see http://php.net/session-set-save-handler
  259
+     * @see http://php.net/sessionhandlerinterface
276 260
      */
277 261
     protected function registerSaveHandlers()
278 262
     {
@@ -295,6 +279,8 @@ protected function registerSaveHandlers()
295 279
      *
296 280
      * This method is required to avoid strange issues when using PHP objects as
297 281
      * session save handlers.
  282
+     *
  283
+     * @see http://php.net/register-shutdown-function
298 284
      */
299 285
     protected function registerShutdownFunction()
300 286
     {
@@ -305,8 +291,8 @@ protected function registerShutdownFunction()
305 291
      * Load the session with attributes.
306 292
      *
307 293
      * After starting the session, PHP retrieves the session from whatever handlers
308  
-     * are set to (either PHP's internal, custom set with session_set_save_handler()).
309  
-     * PHP takes the return value from the sessionRead() handler, unserializes it
  294
+     * are set to (either PHP's internal, or a custom save handler set with session_set_save_handler()).
  295
+     * PHP takes the return value from the read() handler, unserializes it
310 296
      * and populates $_SESSION with the result automatically.
311 297
      *
312 298
      * @param array|null $session
6  src/Symfony/Component/HttpFoundation/Session/Storage/MemcacheSessionStorage.php
@@ -42,9 +42,9 @@ class MemcacheSessionStorage extends AbstractSessionStorage implements \SessionH
42 42
     /**
43 43
      * Constructor.
44 44
      *
45  
-     * @param \Memcache             $memcache        A \Memcache instance
46  
-     * @param array                 $memcacheOptions An associative array of Memcachge options
47  
-     * @param array                 $options         Session configuration options.
  45
+     * @param \Memcache $memcache        A \Memcache instance
  46
+     * @param array     $memcacheOptions An associative array of Memcache options
  47
+     * @param array     $options         Session configuration options.
48 48
      *
49 49
      * @see AbstractSessionStorage::__construct()
50 50
      */
11  src/Symfony/Component/HttpFoundation/Session/Storage/MemcachedSessionStorage.php
@@ -14,6 +14,11 @@
14 14
 /**
15 15
  * MemcachedSessionStorage.
16 16
  *
  17
+ * Memcached based session storage handler based on the Memcached class
  18
+ * provided by the PHP memcached extension.
  19
+ *
  20
+ * @see http://php.net/memcached
  21
+ *
17 22
  * @author Drak <drak@zikula.org>
18 23
  */
19 24
 class MemcachedSessionStorage extends AbstractSessionStorage implements \SessionHandlerInterface
@@ -35,9 +40,9 @@ class MemcachedSessionStorage extends AbstractSessionStorage implements \Session
35 40
     /**
36 41
      * Constructor.
37 42
      *
38  
-     * @param \Memcached            $memcached        A \Memcached instance
39  
-     * @param array                 $memcachedOptions An associative array of Memcached options
40  
-     * @param array                 $options          Session configuration options.
  43
+     * @param \Memcached $memcached        A \Memcached instance
  44
+     * @param array      $memcachedOptions An associative array of Memcached options
  45
+     * @param array      $options          Session configuration options.
41 46
      *
42 47
      * @see AbstractSessionStorage::__construct()
43 48
      */
4  src/Symfony/Component/HttpFoundation/Session/Storage/MockFileSessionStorage.php
@@ -30,8 +30,8 @@ class MockFileSessionStorage extends MockArraySessionStorage
30 30
     /**
31 31
      * Constructor.
32 32
      *
33  
-     * @param string                $savePath   Path of directory to save session files.
34  
-     * @param array                 $options    Session options.
  33
+     * @param string $savePath Path of directory to save session files.
  34
+     * @param array  $options  Session options.
35 35
      *
36 36
      * @see AbstractSessionStorage::__construct()
37 37
      */
4  src/Symfony/Component/HttpFoundation/Session/Storage/NativeFileSessionStorage.php
@@ -28,8 +28,8 @@ class NativeFileSessionStorage extends AbstractSessionStorage
28 28
     /**
29 29
      * Constructor.
30 30
      *
31  
-     * @param string                $savePath   Path of directory to save session files.
32  
-     * @param array                 $options    Session configuration options.
  31
+     * @param string $savePath Path of directory to save session files.
  32
+     * @param array  $options  Session configuration options.
33 33
      *
34 34
      * @see AbstractSessionStorage::__construct()
35 35
      */
10  src/Symfony/Component/HttpFoundation/Session/Storage/NativeMemcacheSessionStorage.php
@@ -14,7 +14,9 @@
14 14
 /**
15 15
  * NativeMemcacheSessionStorage.
16 16
  *
17  
- * Session based on native PHP memcache database handler.
  17
+ * Driver for the memcache session save hadlers provided by the memcache PHP extension.
  18
+ *
  19
+ * @see http://php.net/memcache
18 20
  *
19 21
  * @author Drak <drak@zikula.org>
20 22
  */
@@ -28,8 +30,8 @@ class NativeMemcacheSessionStorage extends AbstractSessionStorage
28 30
     /**
29 31
      * Constructor.
30 32
      *
31  
-     * @param string                $savePath   Path of memcache server.
32  
-     * @param array                 $options    Session configuration options.
  33
+     * @param string $savePath Path of memcache server.
  34
+     * @param array  $options  Session configuration options.
33 35
      *
34 36
      * @see AbstractSessionStorage::__construct()
35 37
      */
@@ -57,7 +59,7 @@ protected function registerSaveHandlers()
57 59
      *
58 60
      * Sets any values memcached ini values.
59 61
      *
60  
-     * @see http://www.php.net/manual/en/memcache.ini.php
  62
+     * @see http://php.net/memcache.ini
61 63
      */
62 64
     protected function setOptions(array $options)
63 65
     {
8  src/Symfony/Component/HttpFoundation/Session/Storage/NativeMemcachedSessionStorage.php
@@ -14,7 +14,9 @@
14 14
 /**
15 15
  * NativeMemcachedSessionStorage.
16 16
  *
17  
- * Session based on native PHP memcached database handler.
  17
+ * Driver for the memcached session save hadlers provided by the memcached PHP extension.
  18
+ *
  19
+ * @see http://php.net/memcached.sessions
18 20
  *
19 21
  * @author Drak <drak@zikula.org>
20 22
  */
@@ -28,8 +30,8 @@ class NativeMemcachedSessionStorage extends AbstractSessionStorage
28 30
     /**
29 31
      * Constructor.
30 32
      *
31  
-     * @param string                $savePath   Comma separated list of servers: e.g. memcache1.example.com:11211,memcache2.example.com:11211
32  
-     * @param array                 $options    Session configuration options.
  33
+     * @param string $savePath Comma separated list of servers: e.g. memcache1.example.com:11211,memcache2.example.com:11211
  34
+     * @param array  $options  Session configuration options.
33 35
      *
34 36
      * @see AbstractSessionStorage::__construct()
35 37
      */
24  src/Symfony/Component/HttpFoundation/Session/Storage/NativeSqliteSessionStorage.php
@@ -14,7 +14,7 @@
14 14
 /**
15 15
  * NativeSqliteSessionStorage.
16 16
  *
17  
- * Session based on native PHP sqlite database handler.
  17
+ * Driver for the sqlite session save hadlers provided by the SQLite PHP extension.
18 18
  *
19 19
  * @author Drak <drak@zikula.org>
20 20
  */
@@ -28,8 +28,8 @@ class NativeSqliteSessionStorage extends AbstractSessionStorage
28 28
     /**
29 29
      * Constructor.
30 30
      *
31  
-     * @param string                $dbPath     Path to SQLite database file.
32  
-     * @param array                 $options    Session configuration options.
  31
+     * @param string $dbPath  Path to SQLite database file.
  32
+     * @param array  $options Session configuration options.
33 33
      *
34 34
      * @see AbstractSessionStorage::__construct()
35 35
      */
@@ -51,4 +51,22 @@ protected function registerSaveHandlers()
51 51
         ini_set('session.save_handler', 'sqlite');
52 52
         ini_set('session.save_path', $this->dbPath);
53 53
     }
  54
+
  55
+    /**
  56
+     * {@inheritdoc}
  57
+     *
  58
+     * Sets any values sqlite ini values.
  59
+     *
  60
+     * @see http://php.net/sqlite.configuration
  61
+     */
  62
+    protected function setOptions(array $options)
  63
+    {
  64
+        foreach ($options as $key => $value) {
  65
+            if (in_array($key, array('sqlite.assoc_case'))) {
  66
+                ini_set($key, $value);
  67
+            }
  68
+        }
  69
+
  70
+        parent::setOptions($options);
  71
+    }
54 72
 }
6  src/Symfony/Component/HttpFoundation/Session/Storage/PdoSessionStorage.php
@@ -38,9 +38,9 @@ class PdoSessionStorage extends AbstractSessionStorage implements \SessionHandle
38 38
      * Constructor.
39 39
      *
40 40
      *
41  
-     * @param \PDO                  $pdo        A \PDO instance
42  
-     * @param array                 $dbOptions  An associative array of DB options
43  
-     * @param array                 $options    Session configuration options
  41
+     * @param \PDO  $pdo       A \PDO instance
  42
+     * @param array $dbOptions An associative array of DB options
  43
+     * @param array $options   Session configuration options
44 44
      *
45 45
      * @throws \InvalidArgumentException When "db_table" option is not provided
46 46
      *

0 notes on commit 8280033

Please sign in to comment.
Something went wrong with that request. Please try again.