www.aleph1.co.uk Git - yaffs-website/blob - vendor/symfony/http-foundation/Session/Storage/SessionStorageInterface.php

   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      * @return bool True if started
  28      *
  29      * @throws \RuntimeException If something goes wrong starting the session.
  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 }