/symphony/lib/core/class.cookie.php

<?php

	/**
	 * @package core
	 */
	if(!defined('__IN_SYMPHONY__')) die('<h2>Symphony Error</h2><p>You cannot directly access this file</p>');

	/**
	 * The Cookie class is a wrapper to save Symphony cookies. Typically this
	 * is used to maintain if an Author is logged into Symphony, or by extensions
	 * to determine similar things. The Cookie class is tightly integrated with
	 * PHP's `$_SESSION` global and it's related functions.
	 */
	require_once(CORE . '/class.session.php');

	Class Cookie{

		/**
		 * Used to prevent Symphony cookies from completely polluting the
		 * `$_SESSION` array. This will act as a key and all
		 * cookies will live under that key. By default, the index is read from
		 * the Symphony configuration, and unless changed, is `sym-`
		 *
		 * @var string
		 */
		private $_index;

		/**
		 * This variable determines if the Cookie was set by the Symphony Session
		 * class, or if it was set directly. By default, this is false as the Symphony cookie
		 * created directly in the Symphony constructor, otherwise it will be an instance
		 * of the Session class
		 *
		 * @see core.Symphony#__construct()
		 * @var Session|boolean
		 */
		private $_session = false;

		/**
		 * How long this cookie is valid for. By default, this is 0 if used by an extension,
		 * but it is usually set for 2 weeks in the Symphony context.
		 *
		 * @var integer
		 */
		private $_timeout = 0;

		/**
		 * The path that this cookie is valid for, by default Symphony makes this the whole
		 * domain using /
		 *
		 * @var string
		 */
		private $_path;

		/**
		 * The domain that this cookie is valid for. This is null by default which implies
		 * the entire domain and all subdomains created will have access to this cookie.
		 *
		 * @var string
		 */
		private $_domain;

		/**
		 * Determines whether this cookie can be read by Javascript or not, by default
		 * this is set to true, meaning cookies written by Symphony cannot be read by Javascript
		 *
		 * @var boolean
		 */
		private $_httpOnly = true;

		/**
		 * Determines whether this cookie will be sent over a secure connection or not. If
		 * true, this cookie will only be sent on a secure connection. Defaults to false
		 * but will automatically be set if `__SECURE__` is true
		 *
		 * @since Symphony 2.3.3
		 * @see boot
		 * @var boolean
		 */
		private $_secure = false;

		/**
		 * Constructor for the Cookie class intialises all class variables with the
		 * given parameters. Most of the parameters map to PHP's setcookie
		 * function. It creates a new Session object via the `$this->__init()`
		 *
		 * @see __init()
		 * @link http://php.net/manual/en/function.setcookie.php
		 * @param string $index
		 *  The prefix to used to namespace all Symphony cookies
		 * @param integer $timeout
		 *  The Time to Live for a cookie, by default this is zero, meaning the
		 *  cookie never expires
		 * @param string $path
		 *  The path the cookie is valid for on the domain
		 * @param string $domain
		 *  The domain this cookie is valid for
		 * @param boolean $httpOnly
		 *  Whether this cookie can be read by Javascript. By default the cookie
		 *  cannot be read by Javascript
		 */
		public function __construct($index, $timeout = 0, $path = '/', $domain = NULL, $httpOnly = true) {
			$this->_index = $index;
			$this->_timeout = $timeout;
			$this->_path = $path;
			$this->_domain = $domain;
			$this->_httpOnly = $httpOnly;
			if(defined(__SECURE__)) $this->_secure = __SECURE__;

			$this->_session = $this->__init();
		}

		/**
		 * Initialises a new Session instance using this cookie's params
		 *
		 * @return Session
		 */
		private function __init() {
			$this->_session = Session::start($this->_timeout, $this->_path, $this->_domain, $this->_httpOnly, $this->_secure);
			if (!$this->_session) return false;

			if (!isset($_SESSION[$this->_index])) $_SESSION[$this->_index] = array();

			// Class FrontendPage uses $_COOKIE directly (inside it's __buildPage() function), so try to emulate it.
			$_COOKIE[$this->_index] = &$_SESSION[$this->_index];

			return $this->_session;
		}

		/**
		 * A basic setter, which will set a value to a given property in the
		 * `$_SESSION` array, stored in the key of `$this->_index`
		 *
		 * @param string $name
		 *  The name of the property
		 * @param string $value
		 *  The value of the property
		 */
		public function set($name, $value) {
			$_SESSION[$this->_index][$name] = $value;
		}

		/**
		 * Accessor function for properties in the `$_SESSION` array
		 *
		 * @param string $name
		 *  The name of the property to retrieve (optional)
		 * @return string|null
		 *  The value of the property, or null if it does not exist. If
		 *  no `$name` is provided, return the entire Cookie.
		 */
		public function get($name = null) {
			if(is_null($name) && isset($_SESSION[$this->_index])) {
				return $_SESSION[$this->_index];
			}

			if (isset($_SESSION[$this->_index]) && is_array($_SESSION[$this->_index]) && array_key_exists($name, $_SESSION[$this->_index])) {
				return $_SESSION[$this->_index][$name];
			}

			return null;
		}

		/**
		 * Expires the current `$_SESSION` by unsetting the Symphony
		 * namespace (`$this->_index`). If the `$_SESSION`
		 * is empty, the function will destroy the entire `$_SESSION`
		 *
		 * @link http://au2.php.net/manual/en/function.session-destroy.php
		 */
		public function expire() {
			if(!isset($_SESSION[$this->_index]) || !is_array($_SESSION[$this->_index]) || empty($_SESSION[$this->_index])) return;

			unset($_SESSION[$this->_index]);

			// Calling session_destroy triggers the Session::destroy function which removes the entire session
			// from the database. To prevent logout issues between functionality that relies on $_SESSION, such
			// as Symphony authentication or the Members extension, only delete the $_SESSION if it empty!
			if(empty($_SESSION)) session_destroy();
		}

	}