Permalink
Browse files

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...
fabpot committed Mar 1, 2012
2 parents 4c1cea7 + 09be5cb commit 828003313eb4025b25c9c8205c4a99b21aab6f0f
@@ -10,43 +10,15 @@
*/
/**
- * Session Savehandler Interface.
+ * SessionHandlerInterface
*
- * This interface is for implementing methods required for the
- * session_set_save_handler() function.
+ * Provides forward compatability with PHP 5.4
*
- * @see http://php.net/session_set_save_handler
+ * Extensive documentation can be found at php.net, see links:
*
- * These are methods called by PHP when the session is started
- * and closed and for various house-keeping tasks required
- * by session management.
- *
- * PHP requires session save handlers. There are some defaults set
- * automatically when PHP starts, but these can be overriden using
- * this command if you need anything other than PHP's default handling.
- *
- * When the session starts, PHP will call the read() handler
- * which should return a string extactly as stored (which will have
- * been encoded by PHP using a special session serializer session_decode()
- * which is different to the serialize() function. PHP will then populate
- * these into $_SESSION.
- *
- * When PHP shuts down, the write() handler is called and will pass
- * the $_SESSION contents already serialized (using session_encode()) to
- * be stored.
- *
- * When a session is specifically destroyed, PHP will call the
- * destroy() handler with the session ID. This happens when the
- * session is regenerated for example and th handler MUST delete the
- * session by ID from the persistent storage immediately.
- *
- * PHP will call gc() from time to time to expire any session
- * records according to the set max lifetime of a session. This routine
- * should delete all records from persistent storage which were last
- * accessed longer than the $lifetime.
- *
- * PHP open() and close() are pretty much redundant and
- * can return true.
+ * @see http://php.net/sessionhandlerinterface
+ * @see http://php.net/session.customhandler
+ * @see http://php.net/session-set-save-handler
*
* @author Drak <drak@zikula.org>
*/
@@ -55,7 +27,7 @@
/**
* Open session.
*
- * This method is for internal use by PHP and must not be called manually.
+ * @see http://php.net/sessionhandlerinterface.open
*
* @param string $savePath Save path.
* @param string $sessionName Session Name.
@@ -69,7 +41,7 @@ function open($savePath, $sessionName);
/**
* Close session.
*
- * This method is for internal use by PHP and must not be called manually.
+ * @see http://php.net/sessionhandlerinterface.close
*
* @return boolean
*/
@@ -78,19 +50,7 @@ function close();
/**
* Read session.
*
- * This method is for internal use by PHP and must not be called manually.
- *
- * This method is called by PHP itself when the session is started.
- * This method should retrieve the session data from storage by the
- * ID provided by PHP. Return the string directly as is from storage.
- * If the record was not found you must return an empty string.
- *
- * The returned data will be unserialized automatically by PHP using a
- * special unserializer method session_decode() and the result will be used
- * to populate the $_SESSION superglobal. This is done automatically and
- * is not configurable.
- *
- * @param string $sessionId Session ID.
+ * @see http://php.net/sessionhandlerinterface.read
*
* @throws \RuntimeException On fatal error but not "record not found".
*
@@ -101,33 +61,19 @@ function read($sessionId);
/**
* Commit session to storage.
*
- * This method is for internal use by PHP and must not be called manually.
- *
- * PHP will call this method when the session is closed. It sends
- * the session ID and the contents of $_SESSION to be saved in a lightweight
- * serialized format (which PHP does automatically using session_encode()
- * which should be stored exactly as is given in $data.
- *
- * Note this method is normally called by PHP after the output buffers
- * have been closed.
+ * @see http://php.net/sessionhandlerinterface.write
*
* @param string $sessionId Session ID.
* @param string $data Session serialized data to save.
*
- * @throws \RuntimeException On fatal error.
- *
* @return boolean
*/
function write($sessionId, $data);
/**
* Destroys this session.
*
- * This method is for internal use by PHP and must not be called manually.
- *
- * PHP will call this method when the session data associated
- * with the session ID provided needs to be immediately
- * deleted from the permanent storage.
+ * @see http://php.net/sessionhandlerinterface.destroy
*
* @param string $sessionId Session ID.
*
@@ -140,10 +86,7 @@ function destroy($sessionId);
/**
* Garbage collection for storage.
*
- * This method is for internal use by PHP and must not be called manually.
- *
- * This method is called by PHP periodically and passes the maximum
- * time a session can exist for before being deleted from permanent storage.
+ * @see http://php.net/sessionhandlerinterface.gc
*
* @param integer $lifetime Max lifetime in seconds to keep sessions stored.
*
@@ -16,6 +16,13 @@
/**
* This provides a base class for session attribute storage.
*
+ * This can be used to implement internal PHP session handlers
+ * provided by PHP extensions or custom session save handlers
+ * implementing the \SessionHandlerInterface
+ *
+ * @see http://php.net/session.customhandler
+ * @see http://php.net/sessionhandlerinterface
+ *
* @author Drak <drak@zikula.org>
*/
abstract class AbstractSessionStorage implements SessionStorageInterface
@@ -49,11 +56,11 @@
* want top override this constructor entirely.
*
* List of options for $options array with their defaults.
- * @see http://www.php.net/manual/en/session.configuration.php for options
- * but we omit 'session.' from the beginning of the keys.
+ * @see http://php.net/session.configuration for options
+ * but we omit 'session.' from the beginning of the keys for convenience.
*
* auto_start, "0"
- * cache_limiter, ""
+ * cache_limiter, "nocache" (use "0" to prevent headers from being sent entirely).
* cookie_domain, ""
* cookie_httponly, ""
* cookie_lifetime, "0"
@@ -81,7 +88,7 @@
* upload_progress.min-freq, "1"
* url_rewriter.tags, "a=href,area=href,frame=src,form=,fieldset="
*
- * @param array $options Session configuration options.
+ * @param array $options Session configuration options.
*/
public function __construct(array $options = array())
{
@@ -196,7 +203,7 @@ public function getBag($name)
*
* @param array $options
*
- * @see http://www.php.net/manual/en/session.configuration.php
+ * @see http://php.net/session.configuration
*/
protected function setOptions(array $options)
{
@@ -240,39 +247,16 @@ protected function setOptions(array $options)
}
/**
- * Registers this storage device for PHP session handling.
- *
- * PHP requires session save handlers to be set, either it's own, or custom ones.
- * There are some defaults set automatically when PHP starts, but these can be overriden
- * using this command if you need anything other than PHP's default handling.
- *
- * When the session starts, PHP will call the sessionRead() handler which should return an array
- * of any session attributes. PHP will then populate these into $_SESSION.
- *
- * When PHP shuts down, the write() handler is called and will pass the $_SESSION contents
- * to be stored.
+ * Registers this storage device as a PHP session handler.
*
- * When a session is specifically destroyed, PHP will call the destroy() handler with the
- * session ID. This happens when the session is regenerated for example and th handler
- * MUST delete the session by ID from the persistent storage immediately.
- *
- * PHP will call gc() from time to time to expire any session records according to the
- * set max lifetime of a session. This routine should delete all records from persistent
- * storage which were last accessed longer than the $lifetime.
- *
- * PHP open() and close() are pretty much redundant and can just return true.
- *
- * NOTE:
- *
- * To use PHP native save handlers, override this method using ini_set with
+ * To use internal PHP session save handlers, override this method using ini_set with
* session.save_handlers and session.save_path e.g.
*
* ini_set('session.save_handlers', 'files');
* ini_set('session.save_path', /tmp');
*
- * @see http://php.net/manual/en/function.session-set-save-handler.php
- * @see \SessionHandlerInterface
- * @see http://php.net/manual/en/class.sessionhandlerinterface.php
+ * @see http://php.net/session-set-save-handler
+ * @see http://php.net/sessionhandlerinterface
*/
protected function registerSaveHandlers()
{
@@ -295,6 +279,8 @@ protected function registerSaveHandlers()
*
* This method is required to avoid strange issues when using PHP objects as
* session save handlers.
+ *
+ * @see http://php.net/register-shutdown-function
*/
protected function registerShutdownFunction()
{
@@ -305,8 +291,8 @@ protected function registerShutdownFunction()
* Load the session with attributes.
*
* After starting the session, PHP retrieves the session from whatever handlers
- * are set to (either PHP's internal, custom set with session_set_save_handler()).
- * PHP takes the return value from the sessionRead() handler, unserializes it
+ * are set to (either PHP's internal, or a custom save handler set with session_set_save_handler()).
+ * PHP takes the return value from the read() handler, unserializes it
* and populates $_SESSION with the result automatically.
*
* @param array|null $session
@@ -42,9 +42,9 @@ class MemcacheSessionStorage extends AbstractSessionStorage implements \SessionH
/**
* Constructor.
*
- * @param \Memcache $memcache A \Memcache instance
- * @param array $memcacheOptions An associative array of Memcachge options
- * @param array $options Session configuration options.
+ * @param \Memcache $memcache A \Memcache instance
+ * @param array $memcacheOptions An associative array of Memcache options
+ * @param array $options Session configuration options.
*
* @see AbstractSessionStorage::__construct()
*/
@@ -14,6 +14,11 @@
/**
* MemcachedSessionStorage.
*
+ * Memcached based session storage handler based on the Memcached class
+ * provided by the PHP memcached extension.
+ *
+ * @see http://php.net/memcached
+ *
* @author Drak <drak@zikula.org>
*/
class MemcachedSessionStorage extends AbstractSessionStorage implements \SessionHandlerInterface
@@ -35,9 +40,9 @@ class MemcachedSessionStorage extends AbstractSessionStorage implements \Session
/**
* Constructor.
*
- * @param \Memcached $memcached A \Memcached instance
- * @param array $memcachedOptions An associative array of Memcached options
- * @param array $options Session configuration options.
+ * @param \Memcached $memcached A \Memcached instance
+ * @param array $memcachedOptions An associative array of Memcached options
+ * @param array $options Session configuration options.
*
* @see AbstractSessionStorage::__construct()
*/
@@ -30,8 +30,8 @@ class MockFileSessionStorage extends MockArraySessionStorage
/**
* Constructor.
*
- * @param string $savePath Path of directory to save session files.
- * @param array $options Session options.
+ * @param string $savePath Path of directory to save session files.
+ * @param array $options Session options.
*
* @see AbstractSessionStorage::__construct()
*/
@@ -28,8 +28,8 @@ class NativeFileSessionStorage extends AbstractSessionStorage
/**
* Constructor.
*
- * @param string $savePath Path of directory to save session files.
- * @param array $options Session configuration options.
+ * @param string $savePath Path of directory to save session files.
+ * @param array $options Session configuration options.
*
* @see AbstractSessionStorage::__construct()
*/
@@ -14,7 +14,9 @@
/**
* NativeMemcacheSessionStorage.
*
- * Session based on native PHP memcache database handler.
+ * Driver for the memcache session save hadlers provided by the memcache PHP extension.
+ *
+ * @see http://php.net/memcache
*
* @author Drak <drak@zikula.org>
*/
@@ -28,8 +30,8 @@ class NativeMemcacheSessionStorage extends AbstractSessionStorage
/**
* Constructor.
*
- * @param string $savePath Path of memcache server.
- * @param array $options Session configuration options.
+ * @param string $savePath Path of memcache server.
+ * @param array $options Session configuration options.
*
* @see AbstractSessionStorage::__construct()
*/
@@ -57,7 +59,7 @@ protected function registerSaveHandlers()
*
* Sets any values memcached ini values.
*
- * @see http://www.php.net/manual/en/memcache.ini.php
+ * @see http://php.net/memcache.ini
*/
protected function setOptions(array $options)
{
@@ -14,7 +14,9 @@
/**
* NativeMemcachedSessionStorage.
*
- * Session based on native PHP memcached database handler.
+ * Driver for the memcached session save hadlers provided by the memcached PHP extension.
+ *
+ * @see http://php.net/memcached.sessions
*
* @author Drak <drak@zikula.org>
*/
@@ -28,8 +30,8 @@ class NativeMemcachedSessionStorage extends AbstractSessionStorage
/**
* Constructor.
*
- * @param string $savePath Comma separated list of servers: e.g. memcache1.example.com:11211,memcache2.example.com:11211
- * @param array $options Session configuration options.
+ * @param string $savePath Comma separated list of servers: e.g. memcache1.example.com:11211,memcache2.example.com:11211
+ * @param array $options Session configuration options.
*
* @see AbstractSessionStorage::__construct()
*/
Oops, something went wrong.

0 comments on commit 8280033

Please sign in to comment.