1: <?php
  2: 
  3: /*
  4:  * This file is part of the Symfony package.
  5:  *
  6:  * (c) Fabien Potencier <[email protected]>
  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 <[email protected]>
 20:  * @author Drak <[email protected]>
 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: }
140: