<?php

/**

 * Zend Framework

 *

 * LICENSE

 *

 * This source file is subject to the new BSD license that is bundled

 * with this package in the file LICENSE.txt.

 * It is also available through the world-wide-web at this URL:

 * http://framework.zend.com/license/new-bsd

 * If you did not receive a copy of the license and are unable to

 * obtain it through the world-wide-web, please send an email

 * to license@zend.com so we can send you a copy immediately.

 *

 * @category   Zend

 * @package    Zend_Session

 * @copyright  Copyright (c) 2005-2010 Zend Technologies USA Inc. (http://www.zend.com)

 * @license    http://framework.zend.com/license/new-bsd     New BSD License

 * @version    $Id: Session.php 22587 2010-07-16 20:14:18Z ralph $

 * @since      Preview Release 0.2

 */

/**

 * @see Zend_Session_Abstract

 */

require_once 'Zend/Session/Abstract.php';

/**

 * @see Zend_Session_Namespace

 */

require_once 'Zend/Session/Namespace.php';

/**

 * @see Zend_Session_SaveHandler_Interface

 */

require_once 'Zend/Session/SaveHandler/Interface.php';

/**

 * Zend_Session

 *

 * @category   Zend

 * @package    Zend_Session

 * @copyright  Copyright (c) 2005-2010 Zend Technologies USA Inc. (http://www.zend.com)

 * @license    http://framework.zend.com/license/new-bsd     New BSD License

 */

class Zend_Session extends Zend_Session_Abstract

{

    /**

     * Whether or not Zend_Session is being used with unit tests

     *

     * @internal

     * @var bool

     */

    public static $_unitTestEnabled = false;

    /**

     * $_throwStartupException

     *

     * @var bool|bitset This could also be a combiniation of error codes to catch

     */

    protected static $_throwStartupExceptions = true;

    /**

     * Check whether or not the session was started

     *

     * @var bool

     */

    private static $_sessionStarted = false;

    /**

     * Whether or not the session id has been regenerated this request.

     *

     * Id regeneration state

     * <0 - regenerate requested when session is started

     * 0  - do nothing

     * >0 - already called session_regenerate_id()

     *

     * @var int

     */

    private static $_regenerateIdState = 0;

    /**

     * Private list of php's ini values for ext/session

     * null values will default to the php.ini value, otherwise

     * the value below will overwrite the default ini value, unless

     * the user has set an option explicity with setOptions()

     *

     * @var array

     */

    private static $_defaultOptions = array(

        'save_path'                 => null,

        'name'                      => null, /* this should be set to a unique value for each application */

        'save_handler'              => null,

        //'auto_start'                => null, /* intentionally excluded (see manual) */

        'gc_probability'            => null,

        'gc_divisor'                => null,

        'gc_maxlifetime'            => null,

        'serialize_handler'         => null,

        'cookie_lifetime'           => null,

        'cookie_path'               => null,

        'cookie_domain'             => null,

        'cookie_secure'             => null,

        'cookie_httponly'           => null,

        'use_cookies'               => null,

        'use_only_cookies'          => 'on',

        'referer_check'             => null,

        'entropy_file'              => null,

        'entropy_length'            => null,

        'cache_limiter'             => null,

        'cache_expire'              => null,

        'use_trans_sid'             => null,

        'bug_compat_42'             => null,

        'bug_compat_warn'           => null,

        'hash_function'             => null,

        'hash_bits_per_character'   => null

    );

    /**

     * List of options pertaining to Zend_Session that can be set by developers

     * using Zend_Session::setOptions(). This list intentionally duplicates

     * the individual declaration of static "class" variables by the same names.

     *

     * @var array

     */

    private static $_localOptions = array(

        'strict'                => '_strict',

        'remember_me_seconds'   => '_rememberMeSeconds',

        'throw_startup_exceptions' => '_throwStartupExceptions'

    );

    /**

     * Whether or not write close has been performed.

     *

     * @var bool

     */

    private static $_writeClosed = false;

    /**

     * Whether or not session id cookie has been deleted

     *

     * @var bool

     */

    private static $_sessionCookieDeleted = false;

    /**

     * Whether or not session has been destroyed via session_destroy()

     *

     * @var bool

     */

    private static $_destroyed = false;

    /**

     * Whether or not session must be initiated before usage

     *

     * @var bool

     */

    private static $_strict = false;

    /**

     * Default number of seconds the session will be remembered for when asked to be remembered

     *

     * @var int

     */

    private static $_rememberMeSeconds = 1209600; // 2 weeks

    /**

     * Whether the default options listed in Zend_Session::$_localOptions have been set

     *

     * @var bool

     */

    private static $_defaultOptionsSet = false;

    /**

     * A reference to the set session save handler

     *

     * @var Zend_Session_SaveHandler_Interface

     */

    private static $_saveHandler = null;

    /**

     * Constructor overriding - make sure that a developer cannot instantiate

     */

    protected function __construct()

    {

    }

    /**

     * setOptions - set both the class specified

     *

     * @param  array $userOptions - pass-by-keyword style array of <option name, option value> pairs

     * @throws Zend_Session_Exception

     * @return void

     */

    public static function setOptions(array $userOptions = array())

    {

        // set default options on first run only (before applying user settings)

        if (!self::$_defaultOptionsSet) {

            foreach (self::$_defaultOptions as $defaultOptionName => $defaultOptionValue) {

                if (isset(self::$_defaultOptions[$defaultOptionName])) {

                    ini_set("session.$defaultOptionName", $defaultOptionValue);

                }

            }

            self::$_defaultOptionsSet = true;

        }

        // set the options the user has requested to set

        foreach ($userOptions as $userOptionName => $userOptionValue) {

            $userOptionName = strtolower($userOptionName);

            // set the ini based values

            if (array_key_exists($userOptionName, self::$_defaultOptions)) {

                ini_set("session.$userOptionName", $userOptionValue);

            }

            elseif (isset(self::$_localOptions[$userOptionName])) {

                self::${self::$_localOptions[$userOptionName]} = $userOptionValue;

            }

            else {

                /** @see Zend_Session_Exception */

                require_once 'Zend/Session/Exception.php';

                throw new Zend_Session_Exception("Unknown option: $userOptionName = $userOptionValue");

            }

        }

    }

    /**

     * getOptions()

     *

     * @param string $optionName OPTIONAL

     * @return array|string

     */

    public static function getOptions($optionName = null)

    {

        $options = array();

        foreach (ini_get_all('session') as $sysOptionName => $sysOptionValues) {

            $options[substr($sysOptionName, 8)] = $sysOptionValues['local_value'];

        }

        foreach (self::$_localOptions as $localOptionName => $localOptionMemberName) {

            $options[$localOptionName] = self::${$localOptionMemberName};

        }

        if ($optionName) {

            if (array_key_exists($optionName, $options)) {

                return $options[$optionName];

            }

            return null;

        }

        return $options;

    }

    /**

     * setSaveHandler() - Session Save Handler assignment

     *

     * @param Zend_Session_SaveHandler_Interface $interface

     * @return void

     */

    public static function setSaveHandler(Zend_Session_SaveHandler_Interface $saveHandler)

    {

        self::$_saveHandler = $saveHandler;

        if (self::$_unitTestEnabled) {

            return;

        }

        session_set_save_handler(

            array(&$saveHandler, 'open'),

            array(&$saveHandler, 'close'),

            array(&$saveHandler, 'read'),

            array(&$saveHandler, 'write'),

            array(&$saveHandler, 'destroy'),

            array(&$saveHandler, 'gc')

            );

    }

    /**

     * getSaveHandler() - Get the session Save Handler

     *

     * @return Zend_Session_SaveHandler_Interface

     */

    public static function getSaveHandler()

    {

        return self::$_saveHandler;

    }

    /**

     * regenerateId() - Regenerate the session id.  Best practice is to call this after

     * session is started.  If called prior to session starting, session id will be regenerated

     * at start time.

     *

     * @throws Zend_Session_Exception

     * @return void

     */

    public static function regenerateId()

    {

        if (!self::$_unitTestEnabled && headers_sent($filename, $linenum)) {

            /** @see Zend_Session_Exception */

            require_once 'Zend/Session/Exception.php';

            throw new Zend_Session_Exception("You must call " . __CLASS__ . '::' . __FUNCTION__ .

                "() before any output has been sent to the browser; output started in {$filename}/{$linenum}");

        }

        if (self::$_sessionStarted && self::$_regenerateIdState <= 0) {

            if (!self::$_unitTestEnabled) {

                session_regenerate_id(true);

            }

            self::$_regenerateIdState = 1;

        } else {

            /**

             * @todo If we can detect that this requester had no session previously,

             *       then why regenerate the id before the session has started?

             *       Feedback wanted for:

             //

            if (isset($_COOKIE[session_name()]) || (!use only cookies && isset($_REQUEST[session_name()]))) {

                self::$_regenerateIdState = 1;

            } else {

                self::$_regenerateIdState = -1;

            }

            //*/

            self::$_regenerateIdState = -1;

        }

    }

    /**

     * rememberMe() - Write a persistent cookie that expires after a number of seconds in the future. If no number of

     * seconds is specified, then this defaults to self::$_rememberMeSeconds.  Due to clock errors on end users' systems,

     * large values are recommended to avoid undesirable expiration of session cookies.

     *

     * @param $seconds integer - OPTIONAL specifies TTL for cookie in seconds from present time

     * @return void

     */

    public static function rememberMe($seconds = null)

    {

        $seconds = (int) $seconds;

        $seconds = ($seconds > 0) ? $seconds : self::$_rememberMeSeconds;

        self::rememberUntil($seconds);

    }

    /**

     * forgetMe() - Write a volatile session cookie, removing any persistent cookie that may have existed. The session

     * would end upon, for example, termination of a web browser program.

     *

     * @return void

     */

    public static function forgetMe()

    {

        self::rememberUntil(0);

    }

    /**

     * rememberUntil() - This method does the work of changing the state of the session cookie and making

     * sure that it gets resent to the browser via regenerateId()

     *

     * @param int $seconds

     * @return void

     */

    public static function rememberUntil($seconds = 0)

    {

        if (self::$_unitTestEnabled) {

            self::regenerateId();

            return;

        }

        $cookieParams = session_get_cookie_params();

        session_set_cookie_params(

            $seconds,

            $cookieParams['path'],

            $cookieParams['domain'],

            $cookieParams['secure']

            );

        // normally "rememberMe()" represents a security context change, so should use new session id

        self::regenerateId();

    }

    /**

     * sessionExists() - whether or not a session exists for the current request

     *

     * @return bool

     */

    public static function sessionExists()

    {

        if (ini_get('session.use_cookies') == '1' && isset($_COOKIE[session_name()])) {

            return true;

        } elseif (!empty($_REQUEST[session_name()])) {

            return true;

        } elseif (self::$_unitTestEnabled) {

            return true;

        }

        return false;

    }

    /**

     * Whether or not session has been destroyed via session_destroy()

     *

     * @return bool

     */

    public static function isDestroyed()

    {

        return self::$_destroyed;

    }

    /**

     * start() - Start the session.

     *

     * @param bool|array $options  OPTIONAL Either user supplied options, or flag indicating if start initiated automatically

     * @throws Zend_Session_Exception

     * @return void

     */

    public static function start($options = false)

    {

        if (self::$_sessionStarted && self::$_destroyed) {

            require_once 'Zend/Session/Exception.php';

            throw new Zend_Session_Exception('The session was explicitly destroyed during this request, attempting to re-start is not allowed.');

        }

        if (self::$_sessionStarted) {

            return; // already started

        }

        // make sure our default options (at the least) have been set

        if (!self::$_defaultOptionsSet) {

            self::setOptions(is_array($options) ? $options : array());

        }

        // In strict mode, do not allow auto-starting Zend_Session, such as via "new Zend_Session_Namespace()"

        if (self::$_strict && $options === true) {

            /** @see Zend_Session_Exception */

            require_once 'Zend/Session/Exception.php';

            throw new Zend_Session_Exception('You must explicitly start the session with Zend_Session::start() when session options are set to strict.');

        }

        $filename = $linenum = null;

        if (!self::$_unitTestEnabled && headers_sent($filename, $linenum)) {

            /** @see Zend_Session_Exception */

            require_once 'Zend/Session/Exception.php';

            throw new Zend_Session_Exception("Session must be started before any output has been sent to the browser;"

               . " output started in {$filename}/{$linenum}");