<?php
/**
 * Prefs:: provides an API for saving arbitrary values in a user's session.
 * Database save routines to come.
 *
 * @inspiration  Horde 2.0's Prefs class. This one is much simpler, but
 *               the API for the methods that exist are sort of like Horde's
 *               in case we want to be more like it in the future.
 * @author  Quinn Comendant <quinn@strangecode.com>
 * @version 1.1
 */
class Prefs {

    /**
     * Where these preferences can be used. To differentiate between preferences
     * for a specific script, application, or global.
     * @var string $scope
     */
    var $scope = 'global';

    /**
     * Indicator whether we save in the database or not.
     * @var boolean $_perpetual
     */
    var $_perpetual = false;

    /**
     * Hash containing connection parameters.
     * @var array $params
     */
    var $params = array();
    
    
    /**
     * Prefs constructor.
     */
    function __construct($dbh=false, $params=array())
    {
        $this->params = $params;
        $_perpetual = false; // Until database routines are completed.
    }

    /**
     * Sets the default value of a preference. The pref will be set only if
     * is not set already. 
     *
     * @param  string $pref      The name of the preference to modify.
     * @param  string $val       The new value for this preference.
     * @param  string $scope     The scope for this preference.
     *
     * @return boolean  True if the value was successfully set.
     */
    function setDefault($pref, $val, $scope=null)
    {
        if (!isset($scope)) {
            $scope =& $this->scope;
        }
        
        // No empty values allowed.
        if ('' == $pref || '' == $val || '' == $scope) {
            return false;
        }
        
        // Initialized the prefs array.
        if (!isset($_SESSION['_prefs'])) {
            $_SESSION['_prefs'] = array();
        }
        
        // In case boolean or null values are passed as a string.
        if ($val == 'true') {
            $val = true;
        } else if ($val == 'false') {
            $val = false;
        } else if ($val == 'null') {
            $val = null;
        }

        // Set it only if not set already.
        if (!isset($_SESSION['_prefs'][$scope][$pref])) {
            $_SESSION['_prefs'][$scope][$pref] = $val;
            return true;
        }
    }

    /**
     * Sets the given preferences to the specific value, 
     *
     * @param  string $pref      The name of the preference to modify.
     * @param  string $val       The new value for this preference.
     * @param  string $scope     The scope for this preference.
     *
     * @return boolean  True if the value was successfully set.
     */
    function setValue($pref, $val, $scope=null)
    {
        if (!isset($scope)) {
            $scope =& $this->scope;
        }
        
        // No empty values allowed.
        if ('' == $pref || '' == $val || '' == $scope) {
            return false;
        }
        
        // Initialized the prefs array.
        if (!isset($_SESSION['_prefs'])) {
            $_SESSION['_prefs'] = array();
        }
        
        // In case boolean or null values are passed as a string.
        if ($val == 'true') {
            $val = true;
        } else if ($val == 'false') {
            $val = false;
        } else if ($val == 'null') {
            $val = null;
        }

        $_SESSION['_prefs'][$scope][$pref] = $val;
        return true;
    }
    
    /**
     * Returns the value of the requested preference.
     *
     * @param string $pref      The name of the preference to retrieve.
     * @param string $scope     The scope for this preference.
     *
     * @return string           The value of the preference.
     */
    function getValue($pref, $scope=null)
    {
        if (!isset($scope)) {
            $scope =& $this->scope;
        }
        
        return (isset($_SESSION['_prefs'][$scope][$pref])) ? $_SESSION['_prefs'][$scope][$pref] : null;
    }
    
    /**
     * To see if a preference has been set.
     *
     * @param string $pref      The name of the preference to check.
     * @param string $scope     The scope for this preference.
     *
     * @return boolean          True if the preference isset and not empty
     *                          false otherwise.
     */
    function exists($pref, $scope=null)
    {
        if (!isset($scope)) {
            $scope =& $this->scope;
        }
        
        return isset($_SESSION['_prefs'][$scope][$pref]);
    }
    
    /**
     * Clear a set preference value.
     *
     * @param string $pref      The name of the preference to check.
     * @param string $scope     The scope for this preference.
     */
    function clearValue($pref, $scope=null)
    {
        if (!isset($scope)) {
            $scope =& $this->scope;
        }
        
        if (isset($_SESSION['_prefs'][$scope][$pref])) {
            unset($_SESSION['_prefs'][$scope][$pref]);
        }
    }

    /**
     * Retrieves the requested set of preferences from the user's database
     * entry.
     *
     * @param optional array $prefs  An array listing the preferences to
     *                     retrieve. If not specified, retrieve all of the
     *                     preferences listed in the $prefs hash.
     *
     * @return mixed       True on success or a PEAR_Error object on failure. 
     */
    function retrieve()
    {
        // Check that we don't have the preferences loaded yet.
        if ($_SESSION['_prefs']['loaded'] == true || !$_perpetual) {
            return true;
        }

        // Database query goes here....
        
        $_SESSION['_prefs']['loaded'] = true;
    }

    /**
     * Stores preferences to SQL server.
     *
     * @param array $prefs (optional) An array listing the preferences to be
     *                     stored.  If not specified, store all of the
     *                     preferences listed in the $prefs hash.
     *
     * @return mixed       True on success or a PEAR_Error object on failure.
     */
    function store($prefs=array())
    {
        // If we are not storing prefs in perpetually.
        if (!$_perpetual) {
            return true;
        }
        
        /*
         * If a list of preferences to store hasn't been provided in
         * $prefs, assume all preferences are desired.
         */
        if (sizeof($prefs) < 1) {
            $prefs =& $_SESSION['_prefs'];
        } else if ($_SESSION['_prefs']['loaded'] == true) {
            $prefs = array_merge($_SESSION['_prefs'], $prefs);
        }
        
        if (!is_array($prefs) || sizeof($prefs) < 1) {
            raiseMsg(_("No preferences are available."), MSG_ERR, __FILE__, __LINE__);
            dieBoomerangURL();
        }
        
        // Database query goes here....

    }

    /**
     * Perform cleanup operations.
     */
    function cleanup()
    {
        $_SESSION['_prefs'] = array();
    }
}


?>