source: trunk/lib/SessionCache.inc.php @ 1

<?php
/**
 * SessionCache.inc.php
 * Provides an API for storing a limited amount of data
 * intended to have a short lifetime in a user's session.
 *
 * Code by Strangecode :: www.strangecode.com :: This document contains copyrighted information.
 * @author  Quinn Comendant <quinn@strangecode.com>
 * @version 1.2
 * @since   2001
 */
class SessionCache
{
    var $_params = array(
        'soft_limit' => 204800,
        'hard_limit' => 4194304,
        'min_items' => 3,
    );

    /**
     * This method enforces the singleton pattern for this class.
     *
     * @return  object  Reference to the global SessionCache object.
     * @access  public
     * @static
     */
    function &getInstance() {
        static $instance = null;

        if ($instance === null) {
            $instance = new SessionCache();
        }

        return $instance;
    }

    /**
     * Set (or overwrite existing) parameters by passing an array of new parameters.
     *
     * @access public
     * @param  array    $params     Array of parameters (key => val pairs).
     */
    function setParam($params)
    {
        if (isset($params) && is_array($params)) {
            // Merge new parameters with old overriding only those passed.
            $this->_params = array_merge($this->_params, $params);
        } else {
            App::logMsg(sprintf('Parameters are not an array: %s', $params), LOG_ERR, __FILE__, __LINE__);
        }
    }

    /**
     * Return the value of a parameter, if it exists.
     *
     * @access public
     * @param string $param        Which parameter to return.
     * @return mixed               Configured parameter value.
     */
    function getParam($param)
    {
        if (isset($this->_params[$param])) {
            return $this->_params[$param];
        } else {
            App::logMsg(sprintf('Parameter is not set: %s', $param), LOG_DEBUG, __FILE__, __LINE__);
            return null;
        }
    }

    /**
     * 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)
    {
        $cache =& SessionCache::getInstance();

        $var_id = md5($var_id);
        $serialized_var = serialize($var);
        $serialized_var_len = strlen($serialized_var);
        
        if ($serialized_var_len >= $cache->getParam('soft_limit') && !$force_it_in) {
            App::logMsg(sprintf('Serialized variable (%s bytes) more than soft_limit (%s bytes).', $serialized_var_len, $cache->getParam('soft_limit')), LOG_NOTICE, __FILE__, __LINE__);
            return false;
        }
        
        if ($serialized_var_len >= $cache->getParam('hard_limit')) {
            App::logMsg(sprintf('Serialized variable (%s bytes) more than hard_limit (%s bytes).', $serialized_var_len, $cache->getParam('hard_limit')), LOG_NOTICE, __FILE__, __LINE__);
            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 >= $cache->getParam('soft_limit') 
            && sizeof($_SESSION['_session_cache']) >= $cache->getParam('min_items')) {
                array_shift($_SESSION['_session_cache']);
            }
        }
        $_SESSION['_session_cache'][$var_id] =& $serialized_var;
        
        if ($serialized_var_len >= 1024000) {
            App::logMsg(sprintf('Successfully cached oversized variable (%s bytes).', $serialized_var_len), LOG_DEBUG, __FILE__, __LINE__);
        }
        
        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);
        if (isset($_SESSION['_session_cache'][$var_id])) {
            unset($_SESSION['_session_cache'][$var_id]);
        }
    }

// END SessionCache
}

?>