<?php
/**
 * SessionCache.inc.php 
 * Code by Strangecode :: www.strangecode.com :: This document contains copyrighted information
 */

/**
 * The maximum byte size that the session cache will hold.
 * @const SESSION_CACHE_SIZE_BYTES
 */
if (!defined('SESSION_CACHE_SIZE_BYTES')) {
    define('SESSION_CACHE_SIZE_BYTES', 32768); // 32 Kilobytes.
}

/**
 * The cache will never flush out all the items, it will leave this many in.
 * This is in case you cache a very large item and expect it to stay a little
 * longer than having if dumped the next time something goes into the cache.
 * @const SESSION_CACHE_MIN_ITEMS
 */
define('SESSION_CACHE_MIN_ITEMS', 3); // 3 items.


/**
 * SessionCache:: provides an API for storing a limited amount of data
 * intended to have a short lifetime in a user's session.
 *
 * @inspiration     Horde 2.0's SessionCache class.
 * @author  Quinn Comendant <quinn@strangecode.com>
 * @version 1.0
 */
class SessionCache
{

    /**
     * Stores a new variable in the session cache. The $var_id is is md5'ed
     * because if a variable id is a very large integer, the array_shift function
     * will reset the key to the next largest int key. Weird behaviour I can't
     * understand. $session_cache[32341234123] will become $session_cache[0]
     * for example. Usage warning: if the variable is too big to fit, or is
     * old and discarded, you must provide alternative ways of accessing the data.
     *
     * @param mixed $var          The var to store in the session cache.
     * @param str   $var_id       An identifyer for the cached object.
     * @param bool  $force_it_in  If we have something really big that we
     *                            still want to cache, setting this true 
     *                            allows this.
     *
     * @return string        The $var_id, or false if the object was too big to cache.
     */
    function putCache($var, $var_id, $force_it_in=false)
    {
        $var_id = md5($var_id);
        $serialized_var = serialize($var);
        $serialized_var_len = strlen($serialized_var);
        
        if ($serialized_var_len >= 1024000) {
            logMsg(sprintf('Attempting to cache oversized variable at %s bytes.', $serialized_var_len), LOG_NOTICE, __FILE__, __LINE__);
        }
        
        if ($serialized_var_len >= SESSION_CACHE_SIZE_BYTES && !$force_it_in) {
            return false;
        }

        if (!isset($_SESSION['_session_cache'])) {
            $_SESSION['_session_cache'] = array();
        } else {
            unset($_SESSION['_session_cache'][$var_id]);
            // Continue to prune the cache if it's length is too long for the new variable to fit, but keep at least MIN_ITEMS at least.
            while (strlen(serialize($_SESSION['_session_cache'])) + $serialized_var_len >= SESSION_CACHE_SIZE_BYTES 
            && sizeof($_SESSION['_session_cache']) >= SESSION_CACHE_MIN_ITEMS) {
                array_shift($_SESSION['_session_cache']);
            }
        }
        $_SESSION['_session_cache'][$var_id] =& $serialized_var;
        
        return $var_id;
    }
    
    /**
     * Retrives an object from the session cache and returns it unserialized. 
     * It also moves it to the top of the stack, which makes it such that the
     * cache flushing mechanism of putCache deletes the oldest referenced items
     * first.
     *
     * @param string $var_id  The identifyer for the datum to retrieve.
     *
     * @return mixed          The requested datum, or false on failure.
     */
    function getCache($var_id)
    {
        $var_id = md5($var_id);
        if (isset($_SESSION['_session_cache'][$var_id])) {
            // Move the accessed cached datum to the top of the stack. Maybe somebody knows a better way to do this?
            $tmp =& $_SESSION['_session_cache'][$var_id];
            unset($_SESSION['_session_cache'][$var_id]);
            $_SESSION['_session_cache'][$var_id] =& $tmp;
            // Return the unserialized datum.
            return unserialize($_SESSION['_session_cache'][$var_id]);
        } else {
            return false;
        }
    }
    
    /**
     * Tells you if the object is cached.
     *
     * @param string $var_id  The ID of the object to check.
     *
     * @return bool           The return from isset().
     */
    function isCached($var_id)
    {
        $var_id = md5($var_id);
        return isset($_SESSION['_session_cache'][$var_id]);
    }
    
    /**
     * Tells you if the object is cached.
     *
     * @param string $var_id  The ID of the object to check.
     *
     * @return bool           The return from isset().
     */
    function breakCache($var_id)
    {
        $var_id = md5($var_id);
        unset($_SESSION['_session_cache'][$var_id]);
    }

// END SessionCache
}

?>