Class Prefs

Description

The Prefs:: class provides a common abstracted interface into the various preferences storage mediums. It also includes all of the functions for retrieving, storing, and checking preference values.

TODO: document the format of the $_prefs hash here

$_prefs[*pref name*] = array( 'value' => *Default value*, 'locked' => *boolean*, 'shared' => *boolean*, 'type' => 'checkbox' 'text' 'password' 'textarea' 'select' 'number' 'implicit' 'special' 'link' - There must be a field named either 'url' (internal application link) or 'xurl' (external application link) if this type is used. 'enum' 'enum' => TODO, 'desc' => _(*Description string*), 'help' => *Name of the entry in the XML help file* );

Copyright 1999-2009 The Horde Project (http://www.horde.org/)

See the enclosed file COPYING for license information (LGPL). If you did not receive this file, see http://www.fsf.org/copyleft/lgpl.html.

Located in /Prefs/Prefs.php (line 55)


	
			
Direct descendents
Class Description
 class Prefs_file Preferences storage implementation using files in a directory
 class Prefs_imsp Preference storage implementation for an IMSP server.
 class Prefs_kolab_imap Preferences storage implementation for a Kolab IMAP server
 class Prefs_ldap Preferences storage implementation for PHP's LDAP extention.
 class Prefs_session Preferences storage implementation for PHP's session implementation.
 class Prefs_sql Preferences storage implementation for PHP's PEAR database abstraction layer.
Variable Summary
 array $_cache
 boolean $_caching
 array $_hooks
 array $_prefs
 string $_scope
 array $_scopes
 string $_user
Method Summary
 Prefs Prefs ()
 void cleanup ([boolean $all = false])
 void clear ()
 mixed convertFromDriver (mixed $value, string $charset)
 mixed convertToDriver (mixed $value, string $charset)
 Prefs &factory (mixed $driver, [string $scope = 'horde'], [string $user = ''], [string $password = ''], [array $params = null], [boolean $caching = true])
 string getCharset ()
 string getDefault (string $pref)
 string getScope ()
 string getUser ()
 string getValue (string $pref, [boolean $convert = true])
 boolean isDefault (string $pref)
 boolean isDirty (string $pref)
 boolean isLocked (string $pref)
 boolean isShared (string $pref)
 void remove (string $pref)
 void retrieve ([$scope $scope = null])
 void setDefault (string $pref, boolean $bool)
 void setDirty (string $pref, boolean $bool)
 void setLocked (string $pref, boolean $bool)
 void setScope (string $scope)
 void setShared (string $pref, boolean $bool)
 boolean setValue (string $pref, string $val, [boolean $convert = true])
 Prefs &singleton (mixed $driver, [string $scope = 'horde'], [string $user = ''], [string $password = ''], [array $params = null], [boolean $caching = true])
 void store ()
 boolean _cacheLookup ( $scope)
 void _cacheUpdate (string $scope, array $prefs)
 array _dirtyPrefs ()
 string _getPreferenceScope (string $pref)
 void _loadScope ( $scope)
 boolean _setValue (string $pref, string $val, [boolean $dirty = true], [boolean $convert = true])
 void __get ( $name)
 void __set ( $name,  $value)
Variables
array $_cache (line 113)

Array to cache in. Usually a reference to an array in $_SESSION, but could be overridden by a subclass for testing or other users.

boolean $_caching = false (line 105)

Boolean indicating whether preference caching should be used.

array $_hooks = array() (line 120)

Hash holding preferences with hook functions defined.

array $_prefs = array() (line 69)

Hash holding the current set of preferences. Each preference is itself a hash, so this will ultimately be multi-dimensional.

[*pref name*] => Array( [d] => *default value* [m] => *pref mask* [v] => *pref value* )

string $_scope = 'horde' (line 79)

String containing the name of the current scope. This is used to differentiate between sets of preferences (multiple applications can have a "sortby" preference, for example). By default, all preferences belong to the "global" (Horde) scope.

array $_scopes = array() (line 90)

Array of loaded scopes. In order to only load what we need, and

to not load things multiple times, we need to maintain a list of loaded scopes. $this->_prefs will always be the combination of the current scope and the 'horde' scope (or just the 'horde' scope).

string $_user = '' (line 98)

String containing the current username. This indicates the owner of the preferences.

Methods
Constructor Prefs (line 126)

Default constructor (must be called from each extending class in their constructors via parent::Prefs()).

Prefs Prefs ()
cleanup (line 589)

This function provides common cleanup functions for all of the driver implementations.

void cleanup ([boolean $all = false])
  • boolean $all: Clean up all Horde preferences.

Redefined in descendants as:
clear (line 607)

Clears all preferences from the backend.

void clear ()

Redefined in descendants as:
convertFromDriver (line 620)

Converts a value from the driver's charset to the specified charset.

  • return: The converted value.
mixed convertFromDriver (mixed $value, string $charset)
  • mixed $value: A value to convert.
  • string $charset: The charset to convert to.

Redefined in descendants as:
convertToDriver (line 633)

Converts a value from the specified charset to the driver's charset.

  • return: The converted value.
mixed convertToDriver (mixed $value, string $charset)
  • mixed $value: A value to convert.
  • string $charset: The charset to convert from.

Redefined in descendants as:
factory (line 822)

Attempts to return a concrete Prefs instance based on $driver.

  • return: The newly created concrete Prefs instance, or false on error.
Prefs &factory (mixed $driver, [string $scope = 'horde'], [string $user = ''], [string $password = ''], [array $params = null], [boolean $caching = true])
  • mixed $driver: The type of concrete Prefs subclass to return.
  • string $scope: The scope for this set of preferences.
  • string $user: The name of the user who owns this set of preferences.
  • string $password: The password associated with $user.
  • array $params: A hash containing any additional configuration or connection parameters a subclass might need.
  • boolean $caching: Should caching be used?
getCharset (line 159)

Returns the charset used by the concrete preference backend.

  • return: The preference backend's charset.
string getCharset ()

Redefined in descendants as:
getDefault (line 439)

Returns the default value of the given preference.

  • return: The preference's default value.
string getDefault (string $pref)
  • string $pref: The name of the preference to get the default for.
getScope (line 181)

Get the current scope

  • return: The current scope (application)
  • since: Horde 3.2
string getScope ()
getUser (line 169)

Return the user who owns these preferences.

  • return: The user these preferences are for.
string getUser ()
getValue (line 321)

Returns the value of the requested preference.

  • return: The value of the preference, null if it doesn't exist.
string getValue (string $pref, [boolean $convert = true])
  • string $pref: The name of the preference to retrieve.
  • boolean $convert: If true the preference value gets converted from the backend's charset to the current charset.
isDefault (line 455)

Determines if the current preference value is the default value from prefs.php or a user defined value

  • return: True if the preference is the application default value.
boolean isDefault (string $pref)
  • string $pref: The name of the preference to check.
isDirty (line 416)

Returns the state of the "dirty" bit for the given preference.

  • return: The boolean state of $pref's "dirty" bit.
boolean isDirty (string $pref)
  • string $pref: The name of the preference to check.
isLocked (line 370)

Returns the state of the "locked" bit for the given preference.

  • return: The boolean state of $pref's "locked" bit.
boolean isLocked (string $pref)
  • string $pref: The name of the preference to check.
isShared (line 393)

Returns the state of the "shared" bit for the given preference.

  • return: The boolean state of $pref's "shared" bit.
boolean isShared (string $pref)
  • string $pref: The name of the preference to check.
remove (line 203)

Removes a preference entry from the $prefs hash.

void remove (string $pref)
  • string $pref: The name of the preference to remove.
retrieve (line 522)

Retrieves preferences for the current scope + the 'horde' scope.

void retrieve ([$scope $scope = null])
  • $scope $scope: Optional scope specifier - if not present the current scope will be used.
setDefault (line 427)

Modifies the "default" bit for the given preference.

void setDefault (string $pref, boolean $bool)
  • string $pref: The name of the preference to modify.
  • boolean $bool: The new boolean value for the "default" bit.
setDirty (line 404)

Modifies the "dirty" bit for the given preference.

void setDirty (string $pref, boolean $bool)
  • string $pref: The name of the preference to modify.
  • boolean $bool: The new boolean value for the "dirty" bit.
setLocked (line 358)

Modifies the "locked" bit for the given preference.

void setLocked (string $pref, boolean $bool)
  • string $pref: The name of the preference to modify.
  • boolean $bool: The new boolean value for the "locked" bit.
setScope (line 193)

Change scope without explicitly retrieving preferences

  • since: Horde 3.2
void setScope (string $scope)
  • string $scope: The new scope.
setShared (line 381)

Modifies the "shared" bit for the given preference.

void setShared (string $pref, boolean $bool)
  • string $pref: The name of the preference to modify.
  • boolean $bool: The new boolean value for the "shared" bit.
setValue (line 224)

Sets the given preferences ($pref) to the specified value ($val), if the preference is modifiable.

  • return: True if the value was successfully set, false on a failure.
boolean setValue (string $pref, string $val, [boolean $convert = true])
  • string $pref: The name of the preference to modify.
  • string $val: The new value for this preference.
  • boolean $convert: If true the preference value gets converted from the current charset to the backend's charset.
singleton (line 880)

Attempts to return a reference to a concrete Prefs instance based on $driver. It will only create a new instance if no Prefs instance with the same parameters currently exists.

This should be used if multiple preference sources (and, thus, multiple Prefs instances) are required.

This method must be invoked as: $var = &Prefs::singleton()

  • return: The concrete Prefs reference, or false on an error.
Prefs &singleton (mixed $driver, [string $scope = 'horde'], [string $user = ''], [string $password = ''], [array $params = null], [boolean $caching = true])
  • mixed $driver: The type of concrete Prefs subclass to return. If $driver is an array, then we will look in $driver[0]/lib/Prefs/ for the subclass implementation named $driver[1].php.
  • string $scope: The scope for this set of preferences.
  • string $user: The name of the user who owns this set of preferences.
  • string $password: The password associated with $user.
  • array $params: A hash containing any additional configuration or connection parameters a subclass might need.
  • boolean $caching: Should caching be used?
store (line 579)

This function will be run at the end of every request as a shutdown

function (registered by the Prefs:: constructor). All prefs with the dirty bit set will be saved to the storage backend at this time; thus, there is no need to manually call $prefs->store() every time a preference is changed.

  • abstract:
void store ()

Redefined in descendants as:
_cacheLookup (line 695)

Tries to find the requested preferences in the cache. If they exist, update the $_scopes hash with the cached values.

  • return: True on success, false on failure.
  • access: protected
boolean _cacheLookup ( $scope)
  • $scope
_cacheUpdate (line 669)

Updates the session-based preferences cache (if available).

  • access: protected
void _cacheUpdate (string $scope, array $prefs)
  • string $scope: The scope of the prefs being updated.
  • array $prefs: The preferences to update.
_dirtyPrefs (line 646)

Return all "dirty" preferences across all scopes.

  • return: The values for all dirty preferences, in a multi-dimensional array of scope => pref name => pref values.
  • access: protected
array _dirtyPrefs ()
_getPreferenceScope (line 506)

Returns the scope of the given preference.

  • return: The scope of the $pref.
  • access: protected
string _getPreferenceScope (string $pref)
  • string $pref: The name of the preference to examine.
_loadScope (line 545)

Load a specific preference scope.

void _loadScope ( $scope)
  • $scope
_setValue (line 265)

Sets the given preferences ($pref) to the specified value ($val), whether or not the preference is user-modifiable, unset the default bit, and set the dirty bit.

  • return: True if the value was successfully set, false on a failure.
  • access: protected
boolean _setValue (string $pref, string $val, [boolean $dirty = true], [boolean $convert = true])
  • string $pref: The name of the preference to modify.
  • string $val: The new value for this preference.
  • boolean $dirty: True if we should mark the new value as dirty (changed).
  • boolean $convert: If true the preference value gets converted from the current charset to the backend's charset.
__get (line 347)
void __get ( $name)
  • $name
__set (line 242)
void __set ( $name,  $value)
  • $name
  • $value

Documentation generated on Sun, 30 Jan 2011 05:20:40 +0000 by phpDocumentor 1.4.3