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