[HttpFoundation] Documentation.

symfony · ghost · Dec 4, 2011 · Nov 2, 2011 · Nov 4, 2011 · Nov 22, 2011
commit e415277a96b829f17117d7364c88c24c6c6a54e0
diff --git a/CHANGELOG-2.1.md b/CHANGELOG-2.1.md
@@ -144,7 +144,18 @@ To get the diff between two versions, go to https://github.com/symfony/symfony/c
  * added ResponseHeaderBag::makeDisposition() (implements RFC 6266)
  * made mimetype to extension conversion configurable
  * [BC BREAK] Flashes are now stored as a bucket of messages per $type. Moved flash messages 
-   out of the session class.  Must use $session->getFlashBag() to get FlashBag instance.
+   out of the session class.  Must use $session->getFlashBag() to get FlashBagInterface instance. 
+   The flash related methods have been removed from the Session class.  Flashes are now returned 
+   in an array by type, so when processed in the view, adjustments need to be made accordingly.
+ * Flash messages are expired when retrieved (with $clear = true) set.  This makes the implementation
+   more flexible and removed some dependencies in the Session management cycle.
+ * [BC BREAK] SessionStorageInterface has been altered and optionally require SessionSaveHandlerInterface
+   to implement customized session save handlers.
+ * Session now implements SessionInterface making implementation customizable and portable.
+ * Session attributes are now stored in a structured array determined by the key name, separated by dots.
+ * [BC BREAK] Removed NativeSessionStorage and replaced with NativeFileSessionStorage
+ * Added session storage drivers for PHP native, SQLite and Memcache session storage.
+ * Added session storage drivers for custom Memcache and Memcached session storage.
 
 ### HttpKernel
 

diff --git a/UPGRADE-2.1.md b/UPGRADE-2.1.md
@@ -11,7 +11,7 @@ UPGRADE FROM 2.0 to 2.1
   and/or share a common base configuration (i.e. ``config.yml``), merging
   could yield a set of base URL's for multiple environments.
 
-* moved management of the locale from the Session class to the Request class
+* [HttpFoundation] - moved management of the locale from the Session class to the Request class
 
   Configuring the default locale:
 
@@ -40,3 +40,48 @@ UPGRADE FROM 2.0 to 2.1
 
   Before: $session->getLocale()
   After: $request->getLocale()
+
+* [HttpFoundation] Flash Messages.  Moved to own bucket and returns and array based on type.
+
+  Before (PHP):
+
+  <?php if ($view['session']->hasFlash('notice')): ?>
+      <div class="flash-notice">
+          <?php echo $view['session']->getFlash('notice') ?>
+      </div>
+  <?php endif; ?>
+
+  After (PHP):
+
+  <?php if ($view['session']->getFlashBag()->has(FlashBagInterface::NOTICE)): ?>
+      <?php foreach ($view['session']->getFlashBag()->get(FlashBagInterface::NOTICE, true) as $notice): ?>
+          <div class="flash-notice">
+          <?php echo $notice; ?>
+          </div>
+      <?php endforeach; ?>
+  <?php endif; ?>
+
+  Before (Twig):
+
+  {% if app.session.hasFlash('notice') %}
+      <div class="flash-notice">
+          {{ app.session.flash('notice') }}
+      </div>
+  {% endif %}
+
+  After (Twig): (needs review)
+
+  {% if app.session.getFlashBag.has(FlashBagInterface::NOTICE) %}
+      {% for flashMessage in app.session.getFlashBag().get(FlashBagInterface::NOTICE, true) %}
+          <div class="flash-notice">
+              {{ flashMessage }}
+          </div>
+      {% endforeach %}
+  {% endif %}
+
+* [HttpFoundation] SessionStorage\PDOSessionStorage - FlashBagInterface required in constructor.
+
+* [HttpFoundation] Session storage drivers should inherit from SessionStorage\AbstractSessionStorage.
+
+* [HttpFoundation] Any session storage drive that wants to use non-native PHP save handlers should
+                   implement SessionStorage\SessionSaveHandlerInterface
diff --git a/src/Symfony/Component/HttpFoundation/FlashBag.php b/src/Symfony/Component/HttpFoundation/FlashBag.php
@@ -51,7 +51,7 @@ public function initialize(array &$flashes)
      * @param string $message Message.
      * @param string $type    Message category
      */
-    public function add($message, $type = self::STATUS)
+    public function add($message, $type = self::NOTICE)
     {
         $this->flashes[$type][] = $message;
     }

diff --git a/src/Symfony/Component/HttpFoundation/FlashBagInterface.php b/src/Symfony/Component/HttpFoundation/FlashBagInterface.php
@@ -19,7 +19,7 @@
 interface FlashBagInterface
 {
     const STORAGE_KEY = '_sf2_flashes';
-    const STATUS = 'status';
+    const NOTICE = 'notice';
     const ERROR = 'error';
 
     /**

diff --git a/src/Symfony/Component/HttpFoundation/SessionStorage/AbstractSessionStorage.php b/src/Symfony/Component/HttpFoundation/SessionStorage/AbstractSessionStorage.php
@@ -79,82 +79,6 @@ public function __construct(FlashBagInterface $flashBag, array $options = array(
         $this->registerShutdownFunction();
     }
 
-    /**
-     * Sets the session.* ini variables.
-     * 
-     * @param array $options 
-     */
-    protected function setOptions(array $options)
-    {
-        $cookieDefaults = session_get_cookie_params();
-        $this->options = array_merge(array(
-            'lifetime' => $cookieDefaults['lifetime'],
-            'path'     => $cookieDefaults['path'],
-            'domain'   => $cookieDefaults['domain'],
-            'secure'   => $cookieDefaults['secure'],
-            'httponly' => isset($cookieDefaults['httponly']) ? $cookieDefaults['httponly'] : false,
-        ), $options);
-
-        // See session.* for values at http://www.php.net/manual/en/ini.list.php
-        foreach ($this->options as $key => $value) {
-            ini_set('session.'.$key, $value);
-        }
-    }
-
-    /**
-     * Registers this storage device for PHP session handling.
-     * 
-     * If you need this method, please call it during the __construct() of this driver.
-     * 
-     * 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 sessionRead() handler which should return an array
-     * of any session attributes.  PHP will then populate these into $_SESSION.
-     * 
-     * When PHP shuts down, the sessionWrite() handler is called and will pass the $_SESSION contents
-     * to be stored.
-     * 
-     * When a session is specifically destroyed, PHP will call the sessionDestroy() 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 sessionGc() 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 sessionOpen() and sessionClose() are pretty much redundant and can return true.
-     * 
-     * @see http://php.net/manual/en/function.session-set-save-handler.php
-     */
-    protected function registerSaveHandlers()
-    {
-        // note this can be reset to PHP's control using ini_set('session.save_handler', 'files');
-        // so long as ini_set() is called before the session is started.
-        if ($this instanceof SessionSaveHandlerInterface) {
-            session_set_save_handler(
-                    array($this, 'open'), 
-                    array($this, 'close'), 
-                    array($this, 'read'), 
-                    array($this, 'write'), 
-                    array($this, 'destroy'), 
-                    array($this, 'gc')
-                    );
-        }
-    }
-
-    /**
-     * Registers PHP shutdown function.
-     * 
-     * This methos is required to avoid strange issues when using PHP objects as 
-     * session save handlers.
-     */
-    protected function registerShutdownFunction()
-    {
-        register_shutdown_function('session_write_close');
-    }
-
     /**
      * Gets the flashbag.
      * 
@@ -216,7 +140,6 @@ public function getId()
     {
         if (!$this->started) {
             return ''; // returning empty is consistent with session_id() behaviour
-            //throw new \RuntimeException('The session has not been started');
         }
 
         return session_id();
@@ -367,12 +290,91 @@ public function clear()
      * an anonymous session to a logged in user session.
      * 
      * @param boolean $destroy
+     * 
+     * @return boolean Returns true on success or false on failure.
      */
     public function regenerate($destroy = false)
     {
         return session_regenerate_id($destroy);
     }
 
+    /**
+     * Sets the session.* ini variables.
+     * 
+     * Note we omit session. from the beginning of the keys.
+     * 
+     * @param array $options 
+     */
+    protected function setOptions(array $options)
+    {
+        $cookieDefaults = session_get_cookie_params();
+        $this->options = array_merge(array(
+            'lifetime' => $cookieDefaults['lifetime'],
+            'path'     => $cookieDefaults['path'],
+            'domain'   => $cookieDefaults['domain'],
+            'secure'   => $cookieDefaults['secure'],
+            'httponly' => isset($cookieDefaults['httponly']) ? $cookieDefaults['httponly'] : false,
+        ), $options);
+
+        // See session.* for values at http://www.php.net/manual/en/ini.list.php
+        foreach ($this->options as $key => $value) {
+            ini_set('session.'.$key, $value);
+        }
+    }
+
+    /**
+     * 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 sessionWrite() handler is called and will pass the $_SESSION contents
+     * to be stored.
+     * 
+     * When a session is specifically destroyed, PHP will call the sessionDestroy() 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 sessionGc() 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 sessionOpen() and sessionClose() are pretty much redundant and can just return true.
+     * 
+     * @see http://php.net/manual/en/function.session-set-save-handler.php
+     * @see SessionSaveHandlerInterface 
+     */
+    protected function registerSaveHandlers()
+    {
+        // note this can be reset to PHP's control using ini_set('session.save_handler', 'files');
+        // so long as ini_set() is called before the session is started.
+        if ($this instanceof SessionSaveHandlerInterface) {
+            session_set_save_handler(
+                    array($this, 'open'), 
+                    array($this, 'close'), 
+                    array($this, 'read'), 
+                    array($this, 'write'), 
+                    array($this, 'destroy'), 
+                    array($this, 'gc')
+                    );
+        }
+    }
+
+    /**
+     * Registers PHP shutdown function.
+     * 
+     * This methos is required to avoid strange issues when using PHP objects as 
+     * session save handlers.
+     */
+    protected function registerShutdownFunction()
+    {
+        register_shutdown_function('session_write_close');
+    }
+
     /**
      * Resolves a path in attributes property and returns it as a reference.
      * 

diff --git a/src/Symfony/Component/HttpFoundation/SessionStorage/SessionSaveHandlerInterface.php b/src/Symfony/Component/HttpFoundation/SessionStorage/SessionSaveHandlerInterface.php
@@ -51,6 +51,8 @@ interface SessionSaveHandlerInterface
 {
     /**
      * Open session.
+     * 
+     * This method is for internal use by PHP and must not be called manually.
      *
      * @param string $savePath    Save path.
      * @param string $sessionName Session Name.
@@ -61,6 +63,8 @@ public function sessionOpen($savePath, $sessionName);
 
     /**
      * Close session.
+     * 
+     * This method is for internal use by PHP and must not be called manually.
      *
      * @return boolean
      */
@@ -69,6 +73,8 @@ public function sessionClose();
     /**
      * 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.
@@ -90,11 +96,12 @@ public function sessionRead($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 variables to be saved in a lightweight 
+     * 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 the $vars argument.  The variables to be saved are taken 
-     * from the $_SESSION superglobal.
+     * 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.
@@ -111,6 +118,8 @@ public function sessionWrite($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.
@@ -126,6 +135,8 @@ public function sessionDestroy($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.  
      * 

diff --git a/tests/Symfony/Tests/Component/HttpFoundation/FlashBagTest.php b/tests/Symfony/Tests/Component/HttpFoundation/FlashBagTest.php
@@ -30,7 +30,7 @@ public function setUp()
     {
         parent::setUp();
         $this->flashBag = new FlashBag();
-        $flashes = array(FlashBagInterface::STATUS => array('A previous flash message'));
+        $flashes = array(FlashBagInterface::NOTICE => array('A previous flash message'));
         $this->flashBag->initialize($flashes);
     }
 

diff --git a/tests/Symfony/Tests/Component/HttpFoundation/SessionTest.php b/tests/Symfony/Tests/Component/HttpFoundation/SessionTest.php
@@ -110,7 +110,7 @@ public function testMigrate()
         $this->session->getFlashBag()->add('OK');
         $this->session->migrate();
         $this->assertEquals(321, $this->session->get('migrate'));
-        $this->assertEquals(array('OK'), $this->session->getFlashBag()->get(FlashBagInterface::STATUS));
+        $this->assertEquals(array('OK'), $this->session->getFlashBag()->get(FlashBagInterface::NOTICE));
     }
 
     public function testSerialize()