[HttpFoundation] Fixed a typo and updated the phpdoc for the session

symfony · fabpot · Feb 12, 2012 · Feb 12, 2012 · Feb 12, 2012 · Feb 12, 2012
commit 5808773b5191a362190a0f779f37d61c4d208311
diff --git a/src/Symfony/Component/HttpFoundation/Session/Attribute/AttributeBagInterface.php b/src/Symfony/Component/HttpFoundation/Session/Attribute/AttributeBagInterface.php
@@ -65,6 +65,8 @@ function replace(array $attributes);
      * Removes an attribute.
      *
      * @param string $name
+     *
+     * @return mixed The removed value
      */
     function remove($name);
 }
diff --git a/src/Symfony/Component/HttpFoundation/Session/Flash/AutoExpireFlashBag.php b/src/Symfony/Component/HttpFoundation/Session/Flash/AutoExpireFlashBag.php
@@ -37,7 +37,7 @@ class AutoExpireFlashBag implements FlashBagInterface
     /**
      * Constructor.
      *
-     * @param type $storageKey The key used to store flashes in the session.
+     * @param string $storageKey The key used to store flashes in the session.
      */
     public function __construct($storageKey = '_sf2_flashes')
     {

diff --git a/src/Symfony/Component/HttpFoundation/Session/Flash/FlashBag.php b/src/Symfony/Component/HttpFoundation/Session/Flash/FlashBag.php
@@ -37,7 +37,7 @@ class FlashBag implements FlashBagInterface
     /**
      * Constructor.
      *
-     * @param type $storageKey The key used to store flashes in the session.
+     * @param string $storageKey The key used to store flashes in the session.
      */
     public function __construct($storageKey = '_sf2_flashes')
     {

diff --git a/src/Symfony/Component/HttpFoundation/Session/Session.php b/src/Symfony/Component/HttpFoundation/Session/Session.php
@@ -50,114 +50,71 @@ public function __construct(SessionStorageInterface $storage, AttributeBagInterf
     }
 
     /**
-     * Starts the session storage.
-     *
-     * @return boolean True if session started.
-     *
-     * @api
+     * {@inheritdoc}
      */
     public function start()
     {
         return $this->storage->start();
     }
 
     /**
-     * Checks if an attribute is defined.
-     *
-     * @param string $name The attribute name
-     *
-     * @return Boolean true if the attribute is defined, false otherwise
-     *
-     * @api
+     * {@inheritdoc}
      */
     public function has($name)
     {
         return $this->storage->getBag('attributes')->has($name);
     }
 
     /**
-     * Returns an attribute.
-     *
-     * @param string $name    The attribute name
-     * @param mixed  $default The default value
-     *
-     * @return mixed
-     *
-     * @api
+     * {@inheritdoc}
      */
     public function get($name, $default = null)
     {
         return $this->storage->getBag('attributes')->get($name, $default);
     }
 
     /**
-     * Sets an attribute.
-     *
-     * @param string $name
-     * @param mixed  $value
-     *
-     * @api
+     * {@inheritdoc}
      */
     public function set($name, $value)
     {
         $this->storage->getBag('attributes')->set($name, $value);
     }
 
     /**
-     * Returns attributes.
-     *
-     * @return array Attributes
-     *
-     * @api
+     * {@inheritdoc}
      */
     public function all()
     {
         return $this->storage->getBag('attributes')->all();
     }
 
     /**
-     * Sets attributes.
-     *
-     * @param array $attributes Attributes
-     *
-     * @api
+     * {@inheritdoc}
      */
     public function replace(array $attributes)
     {
         $this->storage->getBag('attributes')->replace($attributes);
     }
 
     /**
-     * Removes an attribute.
-     *
-     * @param string $name
-     *
-     * @api
+     * {@inheritdoc}
      */
     public function remove($name)
     {
         return $this->storage->getBag('attributes')->remove($name);
     }
 
     /**
-     * Clears all attributes.
-     *
-     * @api
+     * {@inheritdoc}
      */
     public function clear()
     {
         $this->storage->getBag('attributes')->clear();
     }
 
     /**
-     * Invalidates the current session.
-     *
-     * Clears all session attributes and flashes and regenerates the
-     * session and deletes the old session from persistence.
-     *
-     * @return boolean True if session invalidated, false if error.
-     *
-     * @api
+     * {@inheritdoc}
      */
     public function invalidate()
     {
@@ -167,14 +124,7 @@ public function invalidate()
     }
 
     /**
-     * Migrates the current session to a new session id while maintaining all
-     * session attributes.
-     *
-     * @param boolean $destroy Whether to delete the old session or leave it to garbage collection.
-     *
-     * @return boolean True if session migrated, false if error
-     *
-     * @api
+     * {@inheritdoc}
      */
     public function migrate($destroy = false)
     {
@@ -204,7 +154,7 @@ public function getId()
     /**
      * Implements the \Serialize interface.
      *
-     * @return SessionStorageInterface
+     * @return string
      */
     public function serialize()
     {
@@ -214,6 +164,8 @@ public function serialize()
     /**
      * Implements the \Serialize interface.
      *
+     * @param string $serialized
+     *
      * @throws \InvalidArgumentException If the passed string does not unserialize to an instance of SessionStorageInterface
      */
     public function unserialize($serialized)
@@ -261,6 +213,8 @@ public function getFlashBag()
     // the following methods are kept for compatibility with Symfony 2.0 (they will be removed for Symfony 2.3)
 
     /**
+     * @return array
+     *
      * @deprecated since 2.1, will be removed from 2.3
      */
     public function getFlashes()
@@ -269,6 +223,8 @@ public function getFlashes()
     }
 
     /**
+     * @param array $values
+     *
      * @deprecated since 2.1, will be removed from 2.3
      */
     public function setFlashes($values)
@@ -277,6 +233,11 @@ public function setFlashes($values)
     }
 
     /**
+     * @param string $name
+     * @param string $default
+     *
+     * @return string
+     *
      * @deprecated since 2.1, will be removed from 2.3
      */
     public function getFlash($name, $default = null)
@@ -285,6 +246,9 @@ public function getFlash($name, $default = null)
     }
 
     /**
+     * @param string $name
+     * @param string $value
+     *
      * @deprecated since 2.1, will be removed from 2.3
      */
     public function setFlash($name, $value)
@@ -293,6 +257,10 @@ public function setFlash($name, $value)
     }
 
     /**
+     * @param string $name
+     *
+     * @return Boolean
+     *
      * @deprecated since 2.1, will be removed from 2.3
      */
     public function hasFlash($name)
@@ -301,6 +269,8 @@ public function hasFlash($name)
     }
 
     /**
+     * @param string $name
+     *
      * @deprecated since 2.1, will be removed from 2.3
      */
     public function removeFlash($name)
@@ -309,6 +279,8 @@ public function removeFlash($name)
     }
 
     /**
+     * @return array
+     *
      * @deprecated since 2.1, will be removed from 2.3
      */
     public function clearFlashes()

diff --git a/src/Symfony/Component/HttpFoundation/Session/SessionInterface.php b/src/Symfony/Component/HttpFoundation/Session/SessionInterface.php
@@ -21,24 +21,33 @@ interface SessionInterface extends \Serializable
     /**
      * Starts the session storage.
      *
+     * @return Boolean True if session started.
+     *
      * @throws \RuntimeException If session fails to start.
+     *
+     * @api
      */
     function start();
 
     /**
      * Invalidates the current session.
      *
-     * @return boolean True if session invalidated, false if error.
+     * Clears all session attributes and flashes and regenerates the
+     * session and deletes the old session from persistence.
+     *
+     * @return Boolean True if session invalidated, false if error.
+     *
+     * @api
      */
     function invalidate();
 
     /**
      * Migrates the current session to a new session id while maintaining all
      * session attributes.
      *
-     * @param boolean $destroy Whether to delete the old session or leave it to garbage collection.
+     * @param Boolean $destroy Whether to delete the old session or leave it to garbage collection.
      *
-     * @return boolean True if session migrated, false if error.
+     * @return Boolean True if session migrated, false if error.
      *
      * @api
      */
@@ -59,6 +68,8 @@ function save();
      * @param string $name The attribute name
      *
      * @return Boolean true if the attribute is defined, false otherwise
+     *
+     * @api
      */
     function has($name);
 
@@ -69,6 +80,8 @@ function has($name);
      * @param mixed  $default The default value if not found.
      *
      * @return mixed
+     *
+     * @api
      */
     function get($name, $default = null);
 
@@ -77,13 +90,17 @@ function get($name, $default = null);
      *
      * @param string $name
      * @param mixed  $value
+     *
+     * @api
      */
     function set($name, $value);
 
     /**
      * Returns attributes.
      *
      * @return array Attributes
+     *
+     * @api
      */
     function all();
 
@@ -98,11 +115,17 @@ function replace(array $attributes);
      * Removes an attribute.
      *
      * @param string $name
+     *
+     * @return mixed The removed value
+     *
+     * @api
      */
     function remove($name);
 
     /**
      * Clears all attributes.
+     *
+     * @api
      */
     function clear();
 }
diff --git a/src/Symfony/Component/HttpFoundation/Session/Storage/AbstractSessionStorage.php b/src/Symfony/Component/HttpFoundation/Session/Storage/AbstractSessionStorage.php
@@ -128,16 +128,7 @@ public function getId()
     }
 
     /**
-     * Regenerates the session.
-     *
-     * This method will regenerate the session ID and optionally
-     * destroy the old ID. Session regeneration should be done
-     * periodically and for example, should be done when converting
-     * an anonymous session to a logged in user session.
-     *
-     * @param boolean $destroy
-     *
-     * @return boolean Returns true on success or false on failure.
+     * {@inheritdoc}
      */
     public function regenerate($destroy = false)
     {
@@ -171,23 +162,15 @@ public function clear()
     }
 
     /**
-     * Register a SessionBagInterface for use.
-     *
-     * @param SessionBagInterface $bag
+     * {@inheritdoc}
      */
     public function registerBag(SessionBagInterface $bag)
     {
         $this->bags[$bag->getName()] = $bag;
     }
 
     /**
-     * Gets a bag by name.
-     *
     * @param string $name
-     *
-     * @return SessionBagInterface
-     *
-     * @throws \InvalidArgumentException
+     * {@inheritdoc}
      */
     public function getBag($name)
     {
@@ -323,6 +306,8 @@ protected function registerShutdownFunction()
      * 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
      * and populates $_SESSION with the result automatically.
+     *
+     * @param array|null $session
      */
     protected function loadSession(array &$session = null)
     {