[Summary view] [Print] [Text view]

   1  <?php
   2  
   3  /*
   4   * This file is part of the Symfony package.
   5   *
   6   * (c) Fabien Potencier <fabien@symfony.com>
   7   *
   8   * For the full copyright and license information, please view the LICENSE
   9   * file that was distributed with this source code.
  10   */
  11  
  12  namespace Symfony\Component\HttpFoundation\Session\Storage;
  13  
  14  use Symfony\Component\HttpFoundation\Session\SessionBagInterface;
  15  
  16  /**
  17   * StorageInterface.
  18   *
  19   * @author Fabien Potencier <fabien@symfony.com>
  20   * @author Drak <drak@zikula.org>
  21   */
  22  interface SessionStorageInterface
  23  {
  24      /**
  25       * Starts the session.
  26       *
  27       * @throws \RuntimeException If something goes wrong starting the session.
  28       *
  29       * @return bool True if started.
  30       */
  31      public function start();
  32  
  33      /**
  34       * Checks if the session is started.
  35       *
  36       * @return bool True if started, false otherwise.
  37       */
  38      public function isStarted();
  39  
  40      /**
  41       * Returns the session ID.
  42       *
  43       * @return string The session ID or empty.
  44       */
  45      public function getId();
  46  
  47      /**
  48       * Sets the session ID.
  49       *
  50       * @param string $id
  51       */
  52      public function setId($id);
  53  
  54      /**
  55       * Returns the session name.
  56       *
  57       * @return mixed The session name.
  58       */
  59      public function getName();
  60  
  61      /**
  62       * Sets the session name.
  63       *
  64       * @param string $name
  65       */
  66      public function setName($name);
  67  
  68      /**
  69       * Regenerates id that represents this storage.
  70       *
  71       * This method must invoke session_regenerate_id($destroy) unless
  72       * this interface is used for a storage object designed for unit
  73       * or functional testing where a real PHP session would interfere
  74       * with testing.
  75       *
  76       * Note regenerate+destroy should not clear the session data in memory
  77       * only delete the session data from persistent storage.
  78       *
  79       * Care: When regenerating the session ID no locking is involved in PHP's
  80       * session design. See https://bugs.php.net/bug.php?id=61470 for a discussion.
  81       * So you must make sure the regenerated session is saved BEFORE sending the
  82       * headers with the new ID. Symfony's HttpKernel offers a listener for this.
  83       * See Symfony\Component\HttpKernel\EventListener\SaveSessionListener.
  84       * Otherwise session data could get lost again for concurrent requests with the
  85       * new ID. One result could be that you get logged out after just logging in.
  86       *
  87       * @param bool $destroy  Destroy session when regenerating?
  88       * @param int  $lifetime Sets the cookie lifetime for the session cookie. A null value
  89       *                       will leave the system settings unchanged, 0 sets the cookie
  90       *                       to expire with browser session. Time is in seconds, and is
  91       *                       not a Unix timestamp.
  92       *
  93       * @return bool True if session regenerated, false if error
  94       *
  95       * @throws \RuntimeException If an error occurs while regenerating this storage
  96       */
  97      public function regenerate($destroy = false, $lifetime = null);
  98  
  99      /**
 100       * Force the session to be saved and closed.
 101       *
 102       * This method must invoke session_write_close() unless this interface is
 103       * used for a storage object design for unit or functional testing where
 104       * a real PHP session would interfere with testing, in which case
 105       * it should actually persist the session data if required.
 106       *
 107       * @throws \RuntimeException If the session is saved without being started, or if the session
 108       *                           is already closed.
 109       */
 110      public function save();
 111  
 112      /**
 113       * Clear all session data in memory.
 114       */
 115      public function clear();
 116  
 117      /**
 118       * Gets a SessionBagInterface by name.
 119       *
 120       * @param string $name
 121       *
 122       * @return SessionBagInterface
 123       *
 124       * @throws \InvalidArgumentException If the bag does not exist
 125       */
 126      public function getBag($name);
 127  
 128      /**
 129       * Registers a SessionBagInterface for use.
 130       *
 131       * @param SessionBagInterface $bag
 132       */
 133      public function registerBag(SessionBagInterface $bag);
 134  
 135      /**
 136       * @return MetadataBag
 137       */
 138      public function getMetadataBag();
 139  }