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 12namespace Symfony\Component\HttpFoundation\Session\Storage; 13 14use Symfony\Component\HttpFoundation\Session\SessionBagInterface; 15 16/** 17 * StorageInterface. 18 * 19 * @author Fabien Potencier <fabien@symfony.com> 20 * @author Drak <drak@zikula.org> 21 */ 22interface 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 public function setId(string $id); 51 52 /** 53 * Returns the session name. 54 * 55 * @return string The session name 56 */ 57 public function getName(); 58 59 /** 60 * Sets the session name. 61 */ 62 public function setName(string $name); 63 64 /** 65 * Regenerates id that represents this storage. 66 * 67 * This method must invoke session_regenerate_id($destroy) unless 68 * this interface is used for a storage object designed for unit 69 * or functional testing where a real PHP session would interfere 70 * with testing. 71 * 72 * Note regenerate+destroy should not clear the session data in memory 73 * only delete the session data from persistent storage. 74 * 75 * Care: When regenerating the session ID no locking is involved in PHP's 76 * session design. See https://bugs.php.net/61470 for a discussion. 77 * So you must make sure the regenerated session is saved BEFORE sending the 78 * headers with the new ID. Symfony's HttpKernel offers a listener for this. 79 * See Symfony\Component\HttpKernel\EventListener\SaveSessionListener. 80 * Otherwise session data could get lost again for concurrent requests with the 81 * new ID. One result could be that you get logged out after just logging in. 82 * 83 * @param bool $destroy Destroy session when regenerating? 84 * @param int $lifetime Sets the cookie lifetime for the session cookie. A null value 85 * will leave the system settings unchanged, 0 sets the cookie 86 * to expire with browser session. Time is in seconds, and is 87 * not a Unix timestamp. 88 * 89 * @return bool True if session regenerated, false if error 90 * 91 * @throws \RuntimeException If an error occurs while regenerating this storage 92 */ 93 public function regenerate(bool $destroy = false, int $lifetime = null); 94 95 /** 96 * Force the session to be saved and closed. 97 * 98 * This method must invoke session_write_close() unless this interface is 99 * used for a storage object design for unit or functional testing where 100 * a real PHP session would interfere with testing, in which case 101 * it should actually persist the session data if required. 102 * 103 * @throws \RuntimeException if the session is saved without being started, or if the session 104 * is already closed 105 */ 106 public function save(); 107 108 /** 109 * Clear all session data in memory. 110 */ 111 public function clear(); 112 113 /** 114 * Gets a SessionBagInterface by name. 115 * 116 * @return SessionBagInterface 117 * 118 * @throws \InvalidArgumentException If the bag does not exist 119 */ 120 public function getBag(string $name); 121 122 /** 123 * Registers a SessionBagInterface for use. 124 */ 125 public function registerBag(SessionBagInterface $bag); 126 127 /** 128 * @return MetadataBag 129 */ 130 public function getMetadataBag(); 131} 132