[Summary view] [Print] [Text view]

   1  <?php
   2  /**
   3   * Part of the Joomla Framework Session Package
   4   *
   5   * @copyright  Copyright (C) 2005 - 2021 Open Source Matters, Inc. All rights reserved.
   6   * @license    GNU General Public License version 2 or later; see LICENSE
   7   */
   8  
   9  namespace Joomla\Session;
  10  
  11  /**
  12   * Interface defining a Joomla! Session object
  13   *
  14   * @since  2.0.0
  15   */
  16  interface SessionInterface extends \IteratorAggregate
  17  {
  18      /**
  19       * Get expiration time in seconds
  20       *
  21       * @return  integer  The session expiration time in seconds
  22       *
  23       * @since   2.0.0
  24       */
  25  	public function getExpire();
  26  
  27      /**
  28       * Get the session name
  29       *
  30       * @return  string  The session name
  31       *
  32       * @since   2.0.0
  33       */
  34  	public function getName();
  35  
  36      /**
  37       * Set the session name
  38       *
  39       * @param   string  $name  The session name
  40       *
  41       * @return  $this
  42       *
  43       * @since   2.0.0
  44       */
  45  	public function setName(string $name);
  46  
  47      /**
  48       * Get the session ID
  49       *
  50       * @return  string  The session ID
  51       *
  52       * @since   2.0.0
  53       */
  54  	public function getId();
  55  
  56      /**
  57       * Set the session ID
  58       *
  59       * @param   string  $id  The session ID
  60       *
  61       * @return  $this
  62       *
  63       * @since   2.0.0
  64       */
  65  	public function setId(string $id);
  66  
  67      /**
  68       * Check if the session is active
  69       *
  70       * @return  boolean
  71       *
  72       * @since   2.0.0
  73       */
  74  	public function isActive();
  75  
  76      /**
  77       * Check whether this session is newly created
  78       *
  79       * @return  boolean
  80       *
  81       * @since   2.0.0
  82       */
  83  	public function isNew();
  84  
  85      /**
  86       * Check if the session is started
  87       *
  88       * @return  boolean
  89       *
  90       * @since   2.0.0
  91       */
  92  	public function isStarted();
  93  
  94      /**
  95       * Get a session token.
  96       *
  97       * Tokens are used to secure forms from spamming attacks. Once a token has been generated the system will check the request to see if
  98       * it is present, if not it will invalidate the session.
  99       *
 100       * @param   boolean  $forceNew  If true, forces a new token to be created
 101       *
 102       * @return  string
 103       *
 104       * @since   2.0.0
 105       */
 106  	public function getToken($forceNew = false);
 107  
 108      /**
 109       * Check if the session has the given token.
 110       *
 111       * @param   string   $token        Hashed token to be verified
 112       * @param   boolean  $forceExpire  If true, expires the session
 113       *
 114       * @return  boolean
 115       *
 116       * @since   2.0.0
 117       */
 118  	public function hasToken($token, $forceExpire = true);
 119  
 120      /**
 121       * Get data from the session store
 122       *
 123       * @param   string  $name     Name of a variable
 124       * @param   mixed   $default  Default value of a variable if not set
 125       *
 126       * @return  mixed  Value of a variable
 127       *
 128       * @since   2.0.0
 129       */
 130  	public function get($name, $default = null);
 131  
 132      /**
 133       * Set data into the session store
 134       *
 135       * @param   string  $name   Name of a variable.
 136       * @param   mixed   $value  Value of a variable.
 137       *
 138       * @return  mixed  Old value of a variable.
 139       *
 140       * @since   2.0.0
 141       */
 142  	public function set($name, $value = null);
 143  
 144      /**
 145       * Check whether data exists in the session store
 146       *
 147       * @param   string  $name  Name of variable
 148       *
 149       * @return  boolean  True if the variable exists
 150       *
 151       * @since   2.0.0
 152       */
 153  	public function has($name);
 154  
 155      /**
 156       * Unset a variable from the session store
 157       *
 158       * @param   string  $name  Name of variable
 159       *
 160       * @return  mixed   The value from session or NULL if not set
 161       *
 162       * @since   2.0.0
 163       */
 164  	public function remove(string $name);
 165  
 166      /**
 167       * Clears all variables from the session store
 168       *
 169       * @return  void
 170       *
 171       * @since   2.0.0
 172       */
 173  	public function clear();
 174  
 175      /**
 176       * Retrieves all variables from the session store
 177       *
 178       * @return  array
 179       *
 180       * @since   2.0.0
 181       */
 182  	public function all(): array;
 183  
 184      /**
 185       * Start a session
 186       *
 187       * @return  void
 188       *
 189       * @since   2.0.0
 190       */
 191  	public function start();
 192  
 193      /**
 194       * Frees all session variables and destroys all data registered to a session
 195       *
 196       * This method resets the $_SESSION variable and destroys all of the data associated
 197       * with the current session in its storage (file or DB). It forces new session to be
 198       * started after this method is called. It does not unset the session cookie.
 199       *
 200       * @return  boolean
 201       *
 202       * @see     session_destroy()
 203       * @see     session_unset()
 204       * @since   2.0.0
 205       */
 206  	public function destroy();
 207  
 208      /**
 209       * Restart an expired or locked session
 210       *
 211       * @return  boolean  True on success
 212       *
 213       * @see     destroy
 214       * @since   2.0.0
 215       */
 216  	public function restart();
 217  
 218      /**
 219       * Create a new session and copy variables from the old one
 220       *
 221       * @return  boolean
 222       *
 223       * @since   2.0.0
 224       */
 225  	public function fork();
 226  
 227      /**
 228       * Writes session data and ends session
 229       *
 230       * Session data is usually stored after your script terminated without the need
 231       * to call SessionInterface::close(), but as session data is locked to prevent concurrent
 232       * writes only one script may operate on a session at any time. When using
 233       * framesets together with sessions you will experience the frames loading one
 234       * by one due to this locking. You can reduce the time needed to load all the
 235       * frames by ending the session as soon as all changes to session variables are
 236       * done.
 237       *
 238       * @return  void
 239       *
 240       * @see     session_write_close()
 241       * @since   2.0.0
 242       */
 243  	public function close();
 244  
 245      /**
 246       * Perform session data garbage collection
 247       *
 248       * @return  integer|boolean  Number of deleted sessions on success or boolean false on failure or if the function is unsupported
 249       *
 250       * @see     session_gc()
 251       * @since   2.0.0
 252       */
 253      public function gc();
 254  
 255      /**
 256       * Aborts the current session
 257       *
 258       * @return  boolean
 259       *
 260       * @see     session_abort()
 261       * @since   2.0.0
 262       */
 263  	public function abort(): bool;
 264  }