<?php

/**
 * Part of the Joomla Framework Session Package
 *
 * @copyright  Copyright (C) 2005 - 2021 Open Source Matters, Inc. All rights reserved.
 * @license    GNU General Public License version 2 or later; see LICENSE
 */

namespace Joomla\Session;

/**
 * Interface defining a Joomla! Session object
 *
 * @since  2.0.0
 */
interface SessionInterface extends \IteratorAggregate
{
    /**
     * Get expiration time in seconds
     *
     * @return  integer  The session expiration time in seconds
     *
     * @since   2.0.0
     */
    public function getExpire();

    /**
     * Get the session name
     *
     * @return  string  The session name
     *
     * @since   2.0.0
     */
    public function getName();

    /**
     * Set the session name
     *
     * @param   string  $name  The session name
     *
     * @return  $this
     *
     * @since   2.0.0
     */
    public function setName(string $name);

    /**
     * Get the session ID
     *
     * @return  string  The session ID
     *
     * @since   2.0.0
     */
    public function getId();

    /**
     * Set the session ID
     *
     * @param   string  $id  The session ID
     *
     * @return  $this
     *
     * @since   2.0.0
     */
    public function setId(string $id);

    /**
     * Check if the session is active
     *
     * @return  boolean
     *
     * @since   2.0.0
     */
    public function isActive();

    /**
     * Check whether this session is newly created
     *
     * @return  boolean
     *
     * @since   2.0.0
     */
    public function isNew();

    /**
     * Check if the session is started
     *
     * @return  boolean
     *
     * @since   2.0.0
     */
    public function isStarted();

    /**
     * Get a session token.
     *
     * Tokens are used to secure forms from spamming attacks. Once a token has been generated the system will check the request to see if
     * it is present, if not it will invalidate the session.
     *
     * @param   boolean  $forceNew  If true, forces a new token to be created
     *
     * @return  string
     *
     * @since   2.0.0
     */
    public function getToken($forceNew = false);

    /**
     * Check if the session has the given token.
     *
     * @param   string   $token        Hashed token to be verified
     * @param   boolean  $forceExpire  If true, expires the session
     *
     * @return  boolean
     *
     * @since   2.0.0
     */
    public function hasToken($token, $forceExpire = true);

    /**
     * Get data from the session store
     *
     * @param   string  $name     Name of a variable
     * @param   mixed   $default  Default value of a variable if not set
     *
     * @return  mixed  Value of a variable
     *
     * @since   2.0.0
     */
    public function get($name, $default = null);

    /**
     * Set data into the session store
     *
     * @param   string  $name   Name of a variable.
     * @param   mixed   $value  Value of a variable.
     *
     * @return  mixed  Old value of a variable.
     *
     * @since   2.0.0
     */
    public function set($name, $value = null);

    /**
     * Check whether data exists in the session store
     *
     * @param   string  $name  Name of variable
     *
     * @return  boolean  True if the variable exists
     *
     * @since   2.0.0
     */
    public function has($name);

    /**
     * Unset a variable from the session store
     *
     * @param   string  $name  Name of variable
     *
     * @return  mixed   The value from session or NULL if not set
     *
     * @since   2.0.0
     */
    public function remove(string $name);

    /**
     * Clears all variables from the session store
     *
     * @return  void
     *
     * @since   2.0.0
     */
    public function clear();

    /**
     * Retrieves all variables from the session store
     *
     * @return  array
     *
     * @since   2.0.0
     */
    public function all(): array;

    /**
     * Start a session
     *
     * @return  void
     *
     * @since   2.0.0
     */
    public function start();

    /**
     * Frees all session variables and destroys all data registered to a session
     *
     * This method resets the $_SESSION variable and destroys all of the data associated
     * with the current session in its storage (file or DB). It forces new session to be
     * started after this method is called. It does not unset the session cookie.
     *
     * @return  boolean
     *
     * @see     session_destroy()
     * @see     session_unset()
     * @since   2.0.0
     */
    public function destroy();

    /**
     * Restart an expired or locked session
     *
     * @return  boolean  True on success
     *
     * @see     destroy
     * @since   2.0.0
     */
    public function restart();

    /**
     * Create a new session and copy variables from the old one
     *
     * @return  boolean
     *
     * @since   2.0.0
     */
    public function fork();

    /**
     * Writes session data and ends session
     *
     * Session data is usually stored after your script terminated without the need
     * to call SessionInterface::close(), but as session data is locked to prevent concurrent
     * writes only one script may operate on a session at any time. When using
     * framesets together with sessions you will experience the frames loading one
     * by one due to this locking. You can reduce the time needed to load all the
     * frames by ending the session as soon as all changes to session variables are
     * done.
     *
     * @return  void
     *
     * @see     session_write_close()
     * @since   2.0.0
     */
    public function close();

    /**
     * Perform session data garbage collection
     *
     * @return  integer|boolean  Number of deleted sessions on success or boolean false on failure or if the function is unsupported
     *
     * @see     session_gc()
     * @since   2.0.0
     */
    public function gc();

    /**
     * Aborts the current session
     *
     * @return  boolean
     *
     * @see     session_abort()
     * @since   2.0.0
     */
    public function abort(): bool;
}