File Source for _abstractsettings.class.php

<?php
/**
* This file implements the AbstractSettings class designed to handle any kind of settings.
*
* This file is part of Quam Plures - {@link http://quamplures.net/}
* See also {@link https://launchpad.net/quam-plures}.
*
* @copyright (c) 2009 - 2011 by the Quam Plures developers - {@link http://quamplures.net/}
* @copyright (c)2003-2009 by Francois PLANQUE - {@link http://fplanque.net/}
* Parts of this file are copyright (c)2004-2006 by Daniel HAHLER - {@link http://thequod.de/contact}.
*
* {@internal License choice
* - If you have received this file as part of a package, please find the license.txt file in
* the same folder or the closest folder above for complete license terms.
* - If you have received this file individually (e-g: from http://evocms.cvs.sourceforge.net/)
* then you must choose one of the following licenses before using the file:
* - GNU General Public License 2 (GPL) - http://www.opensource.org/licenses/gpl-license.php
* - Mozilla Public License 1.1 (MPL) - http://www.opensource.org/licenses/mozilla1.1.php
* }}}
*
* {@internal Open Source relicensing agreement:
* Daniel HAHLER grants Francois PLANQUE the right to license
* Daniel HAHLER's contributions to this file and the b2evolution project
* under any OSI approved OSS license (http://www.opensource.org/licenses/).
* }}}
*
* {@internal Below is a list of authors who have contributed to design/coding of this file: }}
* @author blueyed: Daniel HAHLER
* @author fplanque: Francois PLANQUE
*
* @package pond
*/
if( !defined('QP_MAIN_INIT') ) die( 'Please, do not access this page directly.' );
/**
* Class to handle settings in an abstract manner (to get used with either 1, 2 or 3 DB column keys).
*
* Arrays and Objects automatically get serialized and unserialized
* (in {@link AbstractSettings::get()} and {@link AbstractSettings::dbupdate()}).
*
* Note: I've evaluated splitting this into single classes for performance reasons, but only
* get() is relevant performance-wise and we could now only get rid of the switch() therein,
* which is not sufficient to split it into *_base + _X classes. (blueyed, 2006-08)
*
* @abstract
* @see UserSettings, GeneralSettings, PluginSettings, CollectionSettings
*
* @package pond
*/
class AbstractSettings
{
/**
* The DB table which stores the settings.
*
* @var string
* @access protected
*/
var $db_table_name;
/**
* Array with DB column key names.
*
* @var array
* @access protected
*/
var $col_key_names = array();
/**
* DB column name for the value.
*
* @var string
* @access protected
*/
var $col_value_name;
/**
* The number of column keys to cache by. This are the first x keys of
* {@link $col_key_names}. 0 means 'load all'.
*
* @var integer
*/
var $cache_by_col_keys;
/**
* The internal cache.
*
* false, if settings could not be loaded or NULL if not initialized.
*
* @access protected
* @var array
*/
var $cache = NULL;
/**
* Do we have loaded everything?
*
* @var boolean
*/
var $all_loaded = false;
/**
* Default settings.
*
* Maps last colkeyname to some default setting that will be used by
* {@link get()} if no value was defined (and it is set as a default).
*
* @var array
*/
var $_defaults = array();
/**
* Constructor.
* @param string The name of the DB table with the settings stored.
* @param array List of names for the DB columns keys that reference a value.
* @param string The name of the DB column that holds the value.
* @param integer The number of column keys to cache by. This are the first x keys of {@link $col_key_names}. 0 means 'load all'.
*/
function AbstractSettings( $db_table_name, $col_key_names, $col_value_name, $cache_by_col_keys = 0 )
{
$this->db_table_name = $db_table_name;
$this->col_key_names = $col_key_names;
$this->col_value_name = $col_value_name;
$this->cache_by_col_keys = $cache_by_col_keys;
/**
* internal counter for the number of column keys
* @var integer
*/
$this->count_col_key_names = count( $this->col_key_names );
if( $this->count_col_key_names > 3 || $this->count_col_key_names < 1 )
{
debug_die( 'Settings keycount not supported for class '.get_class() );
}
}
/**
* Load all settings, disregarding the derived classes setting of
* {@link $cache_by_col_keys} - useful if you know that you want to get
* all user settings for example.
*/
function load_all()
{
return $this->_load();
}
/**
* Loads the settings. Not meant to be called directly, but gets called
* when needed.
*
* @access protected
* @param string First column key
* @param string Second column key
* @param string Third column key
* @return boolean always true
*/
function _load( $arg1 = NULL, $arg2 = NULL, $arg3 = NULL )
{
if( $this->all_loaded )
{ // already all loaded
return true;
}
global $DB;
/**
* The where clause - gets filled when {@link $cache_by_col_keys} is used.
*/
$whereList = array();
if( $this->cache_by_col_keys && isset($arg1) )
{ // The number of column keys to cache by is > 0
$testCache = $this->cache;
$args = array( $arg1, $arg2, $arg3 );
for( $i = 0; $i < $this->cache_by_col_keys; $i++ )
{
$whereList[] = $this->col_key_names[$i]." = '".$args[$i]."'";
if( ! is_array( $testCache )
|| is_null($args[$i])
|| ! isset( $testCache[$args[$i]] )
|| ! ($testCache = & $testCache[$args[$i]]) )
{
break;
}
}
if( $i == $this->cache_by_col_keys )
{ // already loaded!
return true;
}
}
else
{ // We cache everything at once!
$this->all_loaded = true;
}
$result = $DB->get_results( '
SELECT '.implode( ', ', $this->col_key_names ).', '.$this->col_value_name.'
FROM '.$this->db_table_name.(
isset( $whereList[0] )
? ' WHERE '.implode( ' AND ', $whereList )
: '' ) );
switch( $this->count_col_key_names )
{
case 1:
if( ! $result )
{ // Remember that we've tried it
$this->cache[ $arg1 ] = NULL;
}
else foreach( $result as $loop_row )
{
$this->cache[$loop_row->{$this->col_key_names[0]}]->value = $loop_row->{$this->col_value_name};
$this->cache[$loop_row->{$this->col_key_names[0]}]->dbUptodate = true;
$this->cache[$loop_row->{$this->col_key_names[0]}]->dbRemove = false;
}
break;
case 2:
if( ! $result )
{ // Remember that we've tried it
$this->cache[ $arg1 ][ $arg2 ] = NULL;
}
else foreach( $result as $loop_row )
{
$this->cache[$loop_row->{$this->col_key_names[0]}][$loop_row->{$this->col_key_names[1]}]->value = $loop_row->{$this->col_value_name};
$this->cache[$loop_row->{$this->col_key_names[0]}][$loop_row->{$this->col_key_names[1]}]->dbUptodate = true;
$this->cache[$loop_row->{$this->col_key_names[0]}][$loop_row->{$this->col_key_names[1]}]->dbRemove = false;
}
break;
case 3:
if( ! $result )
{ // Remember that we've tried it
$this->cache[ $arg1 ][ $arg2 ][ $arg3 ] = NULL;
}
else foreach( $result as $loop_row )
{
$this->cache[$loop_row->{$this->col_key_names[0]}][$loop_row->{$this->col_key_names[1]}][$loop_row->{$this->col_key_names[2]}]->value = $loop_row->{$this->col_value_name};
$this->cache[$loop_row->{$this->col_key_names[0]}][$loop_row->{$this->col_key_names[1]}][$loop_row->{$this->col_key_names[2]}]->dbUptodate = true;
$this->cache[$loop_row->{$this->col_key_names[0]}][$loop_row->{$this->col_key_names[1]}][$loop_row->{$this->col_key_names[2]}]->dbRemove = false;
}
break;
}
return true;
}
/**
* Get a setting from the DB settings table.
*
* @uses get_default()
* @param string First column key
* @param string Second column key
* @param string Third column key
* @return string|false|NULLvalue as string on success; NULL if not found; false in case of error
*/
function get( $col_key1, $col_key2 = NULL, $col_key3 = NULL )
{
global $debug;
if( $debug )
{
global $Debuglog, $Timer;
$this_class = get_class($this);
$Timer->resume('abstractsettings_'.$this_class.'_get');
}
switch( $this->count_col_key_names )
{
case 1:
$this->_load( $col_key1 );
if( !empty($this->cache[ $col_key1 ]->unserialized) )
{ // The value has been unserialized before:
$r = $this->cache[ $col_key1 ]->value;
}
elseif( isset($this->cache[ $col_key1 ]->value) )
{ // First attempt to access the value, we need to unserialize it:
// Try to unserialize setting (once) - this is as fast as checking an array of values that should get unserialized
if( ($r = @unserialize($this->cache[ $col_key1 ]->value)) !== false )
{
$this->cache[ $col_key1 ]->value = $r;
}
else
{
$r = $this->cache[ $col_key1 ]->value;
}
$this->cache[ $col_key1 ]->unserialized = true;
}
else
{ // The value is not in the cache, we use the default:
$r = $this->get_default( $col_key1 );
$this->cache[ $col_key1 ]->value = $r; // remember in cache
$this->cache[ $col_key1 ]->dbUptodate = true;
$this->cache[ $col_key1 ]->unserialized = true;
$from_default = true; // for debug
}
break;
case 2:
$this->_load( $col_key1, $col_key2 );
if( isset($this->cache[ $col_key1 ][ $col_key2 ]->unserialized) )
{
$r = $this->cache[ $col_key1 ][ $col_key2 ]->value;
}
elseif( isset($this->cache[ $col_key1 ][ $col_key2 ]->value) )
{
// Try to unserialize setting (once) - this is as fast as checking an array of values that should get unserialized
if( ($r = @unserialize($this->cache[ $col_key1 ][ $col_key2 ]->value)) !== false )
{
$this->cache[ $col_key1 ][ $col_key2 ]->value = $r;
}
else
{
$r = $this->cache[ $col_key1 ][ $col_key2 ]->value;
}
$this->cache[ $col_key1 ][ $col_key2 ]->unserialized = true;
}
else
{
$r = $this->get_default( $col_key2 );
$this->cache[ $col_key1 ][ $col_key2 ]->value = $r; // remember in cache
$this->cache[ $col_key1 ][ $col_key2 ]->dbUptodate = true;
$this->cache[ $col_key1 ][ $col_key2 ]->unserialized = true;
$from_default = true; // for debug
}
break;
case 3:
$this->_load( $col_key1, $col_key2, $col_key3 );
if( isset($this->cache[ $col_key1 ][ $col_key2 ][ $col_key3 ]->unserialized) )
{
$r = $this->cache[ $col_key1 ][ $col_key2 ][ $col_key3 ]->value;
}
elseif( isset($this->cache[ $col_key1 ][ $col_key2 ][ $col_key3 ]->value) )
{
// Try to unserialize setting (once) - this is as fast as checking an array of values that should get unserialized
if( ($r = @unserialize($this->cache[ $col_key1 ][ $col_key2 ][ $col_key3 ]->value)) !== false )
{
$this->cache[ $col_key1 ][ $col_key2 ][ $col_key3 ]->value = $r;
}
else
{
$r = $this->cache[ $col_key1 ][ $col_key2 ][ $col_key3 ]->value;
}
$this->cache[ $col_key1 ][ $col_key2 ][ $col_key3 ]->unserialized = true;
}
else
{
$r = $this->get_default( $col_key3 );
$this->cache[ $col_key1 ][ $col_key2 ][ $col_key3 ]->value = $r; // remember in cache
$this->cache[ $col_key1 ][ $col_key2 ][ $col_key3 ]->dbUptodate = true;
$this->cache[ $col_key1 ][ $col_key2 ][ $col_key3 ]->unserialized = true;
$from_default = true; // for debug
}
break;
}
if( $debug )
{
$Debuglog->add( $this_class.'::get( '.$col_key1.'/'.$col_key2.'/'.$col_key3.' ): '
.( isset($from_default) ? '[DEFAULT]: ' : '' )
.var_export( $r, true ), 'settings' );
$Timer->pause('abstractsettings_'.$this_class.'_get');
}
return $r;
}
/**
* Get the default for the last key of {@link $col_key_names}
*
* @param string The last column key
* @return NULL|mixedNULL if no default is set, otherwise the value (should be string).
*/
function get_default( $last_key )
{
if( isset($this->_defaults[ $last_key ]) )
{
return $this->_defaults[ $last_key ];
}
return NULL;
}
/**
* Only set the first variable (passed by reference) if we could retrieve a
* setting.
*
* @param mixed variable to set maybe (by reference)
* @param string the values for the column keys (depends on $this->col_key_names
* and must match its count and order)
* @return boolean true on success (variable was set), false if not
*/
function get_cond( & $toset )
{
$args = func_get_args();
array_shift( $args );
$result = call_user_func_array( array( & $this, 'get' ), $args );
if( $result !== NULL && $result !== false )
{ // No error and value retrieved
$toset = $result;
return true;
}
else
{
return false;
}
}
/**
* Temporarily sets a setting ({@link dbupdate()} writes it to DB).
*
* @param string $args,... the values for the {@link $col_key_names column keys}
* and {@link $col_value_name column value}. Must match order and count!
* @return boolean true, if the value has been set, false if it has not changed.
*/
function set()
{
global $Debuglog;
$args = func_get_args();
$value = array_pop($args);
call_user_func_array( array(&$this, '_load'), $args );
$debugMsg = get_class($this).'::set( '.implode(', ', $args ).' ): ';
switch( $this->count_col_key_names )
{
case 1:
$atCache = & $this->cache[ $args[0] ];
break;
case 2:
$atCache = & $this->cache[ $args[0] ][ $args[1] ];
break;
case 3:
$atCache = & $this->cache[ $args[0] ][ $args[1] ][ $args[2] ];
break;
default:
return false;
}
$atCache->dbRemove = false;
if( isset($atCache->value) )
{
if( $atCache->value == $value )
{ // already set
$Debuglog->add( $debugMsg.' Already set to the same value.', 'settings' );
return false;
}
}
$atCache->value = $value;
$atCache->dbUptodate = false;
$atCache->unserialized = false; // We haven't tried to unserialize the value yet
$Debuglog->add( $debugMsg.' SET!', 'settings' );
return true;
}
/**
* Set an array of values.
*
* @param array Array of parameters for {@link set()}
*/
function set_array( $array )
{
foreach( $array as $lSet )
{
call_user_func_array( array( & $this, 'set' ), $lSet );
}
}
/**
* Remove a setting.
*
* @param array List of {@link $col_key_names}
* @return boolean
*/
function delete( $args )
{
$args = func_get_args();
switch( $this->count_col_key_names )
{
case 1:
$atCache = & $this->cache[ $args[0] ];
break;
case 2:
$atCache = & $this->cache[ $args[0] ][ $args[1] ];
break;
case 3:
$atCache = & $this->cache[ $args[0] ][ $args[1] ][ $args[2] ];
break;
default:
return false;
}
$atCache->dbRemove = true;
unset($atCache->unserialized);
unset($atCache->value);
return true;
}
/**
* Delete an array of values.
*
* @param array Array of parameters for {@link delete()}
*/
function delete_array( $array )
{
foreach( $array as $lDel )
{
call_user_func_array( array( & $this, 'delete' ), $lDel );
}
}
/**
* Delete values for {@link $_defaults default settings} in DB.
*
* This will use the default settings on the next {@link get()}
* again.
*
* @return boolean true, if settings have been updated; false otherwise
*/
function restore_defaults()
{
$this->delete_array( array_keys( $this->_defaults ) );
return $this->dbupdate();
}
/**
* Commit changed settings to DB.
*
* @return boolean true, if settings have been updated; false otherwise
*/
function dbupdate()
{
if( empty($this->cache) )
{
return false;
}
global $DB;
$query_insert = array();
$query_where_delete = array();
switch( $this->count_col_key_names )
{
case 1:
foreach( $this->cache as $key => $value )
{
if( $value === NULL )
{ // Remembered as not existing
continue;
}
if( ! empty($value->dbRemove) )
{
$query_where_delete[] = "{$this->col_key_names[0]} = '$key'";
unset( $this->cache[$key] );
}
elseif( isset($value->dbUptodate) && !$value->dbUptodate )
{
$value = $value->value;
if( is_array( $value ) || is_object( $value ) )
{
$value = serialize($value);
}
$query_insert[] = "('$key', '".$DB->escape( $value )."')";
$this->cache[$key]->dbUptodate = true;
}
}
break;
case 2:
foreach( $this->cache as $key => $value )
{
foreach( $value as $key2 => $value2 )
{
if( $value2 === NULL )
{ // Remembered as not existing
continue;
}
if( ! empty($value2->dbRemove) )
{
$query_where_delete[] = "{$this->col_key_names[0]} = '$key' AND {$this->col_key_names[1]} = '$key2'";
unset( $this->cache[$key][$key2] );
}
elseif( isset($value2->dbUptodate) && !$value2->dbUptodate )
{
$value2 = $value2->value;
if( is_array( $value2 ) || is_object( $value2 ) )
{
$value2 = serialize($value2);
}
$query_insert[] = "('$key', '$key2', '".$DB->escape( $value2 )."')";
$this->cache[$key][$key2]->dbUptodate = true;
}
}
}
break;
case 3:
foreach( $this->cache as $key => $value )
{
foreach( $value as $key2 => $value2 )
{
foreach( $value2 as $key3 => $value3 )
{
if( $value3 === NULL )
{ // Remembered as not existing
continue;
}
if( ! empty($value3->dbRemove) )
{
$query_where_delete[] = "{$this->col_key_names[0]} = '$key' AND {$this->col_key_names[1]} = '$key2' AND {$this->col_key_names[2]} = '$key3'";
unset( $this->cache[$key][$key2][$key3] );
}
elseif( isset($value3->dbUptodate) && !$value3->dbUptodate )
{
$value3 = $value3->value;
if( is_array($value3) || is_object($value3) )
{
$value3 = serialize($value3);
}
$query_insert[] = "('$key', '$key2', '$key3', '".$DB->escape( $value3 )."')";
$this->cache[$key][$key2][$key3]->dbUptodate = true;
}
}
}
}
break;
default:
return false;
}
$r = false;
if( ! empty($query_where_delete) )
{
$query = 'DELETE FROM '.$this->db_table_name." WHERE\n(".implode( ")\nOR (", $query_where_delete ).')';
$r = (boolean)$DB->query( $query );
}
if( ! empty($query_insert) )
{
$query = 'REPLACE INTO '.$this->db_table_name.' ('.implode( ', ', $this->col_key_names ).', '.$this->col_value_name
.') VALUES '.implode(', ', $query_insert);
$r = $DB->query( $query ) || $r;
}
return $r;
}
/**
* Reset cache (includes settings to be written to DB).
*
* This is useful, to rollback settings that have been made, e.g. when a Plugin
* decides that his settings should not get updated.
*/
function reset()
{
$this->cache = NULL;
$this->all_loaded = false;
}
}
?>

Source for file _abstractsettings.class.php