Manual

Provides a framework for managing preferences in applications.

Introduction to Auth_PrefManager

Introduction to Auth_PrefManager – Auth_PrefManager is a simple class to manage user or application preferences from a DB compatible database.

A simple preference manager.

Supported features include:

Setting of default values.
Serialization of values before saving to the database.
Support for any database supported by DB

Tutorial

Tutorial – A short guide to using Auth_PrefManager

Setting up the database

The first step is to setup a database to store the values in. For this tutorial it's assumed that you already know the basics of using the PEAR DB class.

To set up the default table layout run the following SQL statement:

SQL to setup the table

CREATE TABLE `preferences` (
   `user_id` varchar( 255 ) NOT NULL default '',
   `pref_id` varchar( 32 ) NOT NULL default '',
   `pref_value` longtext NOT NULL ,
    PRIMARY KEY ( `user_id` , `pref_id` )
);

Setting up your first PrefManager object

To use Auth_PrefManager we must first create an instance of the base object, as shown below.

Setting up the object

<?php
require_once('Auth/PrefManager.php');
$dsn = 'mysql://user:password@localhost/database';   // Change the DSN to fit your database.
$options = array('serialize' => true);               // Enable serialization of data before saving, this ensures that the values are retrieved cleanly.
$prefmanager = new Auth_PrefManager($dsn, $options); // Create the object.
?>

Setting and displaying default preferences

Now that we have a PrefManager object, we can make use of it to set some preferences.

For this tutorial we're going to allow users to specify their country, and assume that any user who hasn't set their country is somewhere on Earth.

First we need to set the default value, using setDefaultPref.

Setting up the object

<?php
// Continued from example 1.
$prefmanager->setDefaultPref("country", "Earth");
?>

Now that the default is set, we can create a (very) basic page, welcoming users with a customised message.

Currently this message will only ever display "Welcome to the people of Earth!", since no users have their country set.

Getting preferences

$username = "guest";
<h1>Welcome to the people of <?=$prefmanager->getPref($username, "country")?>!</h1>

Setting a user's preferences

Finally we need a way for people to choose which country they're in.

This is going to be done with a simple text box, and you should obviously be a little more careful in a real application about allowing users to set preferences for people!

The Reset Country button will delete the user's preference, and cause the default to be displayed again.

Setting preferences

<h1>Set Country</h1>
// Allow users to set their country and username.
if (isset($_POST['submit'])) {
    $username = htmlspecialchars($_POST['username']);
    $prefmanager->setPref($username, 'country', $_POST['country']);
} else if (isset($_POST['reset'])) {
    $username = htmlspecialchars($_POST['username']);
    $prefmanager->deletePref($username, 'country');
} else {
    $username = 'guest';
}
?>
<h1>Welcome to the people of <?=$prefmanager->getPref($username, "country")?>!</h1>
<h2>Set Country And Username</h2>
<form method="post" action="<?php echo htmlspecialchars($_SERVER['PHP_SELF']) ?>">
  <label for="username">Username</label> <input name="username" value="<?=$username?>" /><br/>
  <label for="country">Country</label> <input name="country" value="<?=$prefmanager->getPref($username, 'country')?>"/><br/>
  <input type="submit" name="submit" value="Set Country" /> <input type="submit" name="reset" value="Reset Country" />
</form>

Now once a user has entered their username, and their country, whenever they login they'll get a personalized welcome.

Full sourcecode

Sourcecode for the example page

<h1>Set Country</h1>
<?php
require_once('Auth/PrefManager.php');

// Create the PrefManager object.

// Change the DSN to fit your database.
$dsn = 'mysql://user:password@localhost/database';   

// Enable serialization of data before saving, this ensures that the values are retrieved cleanly.
$options = array('serialize' => true);               

// Create the object.
$prefmanager = new Auth_PrefManager($dsn, $options); 

// Set the default value (this doesn't need to be done everytime the script is run).
$prefmanager->setDefaultPref("country", "Earth");

// Allow users to set their country and username.
if (isset($_POST['submit'])) {
    $username = htmlspecialchars($_POST['username']);
    $prefmanager->setPref($username, 'country', $_POST['country']);
} else if (isset($_POST['reset'])) {
    $username = htmlspecialchars($_POST['username']);
    $prefmanager->deletePref($username, 'country');
} else {
    $username = 'guest';
}
?>
<h1>Welcome to the people of <?=$prefmanager->getPref($username, "country")?>!</h1>
<h2>Set Country And Username</h2>
<form method="post" action="<?php echo htmlspecialchars($_SERVER['PHP_SELF']) ?>">
  <label for="username">Username</label> <input name="username" value="<?=$username?>" /><br/>
  <label for="country">Country</label> <input name="country" value="<?=$prefmanager->getPref($username, 'country')?>"/><br/>
  <input type="submit" name="submit" value="Set Country" /> <input type="submit" name="reset" value="Reset Country" />
</form>

constructor Auth_PrefManager::Auth_PrefManager

constructor Auth_PrefManager::Auth_PrefManager() – Constructor

Synopsis

require_once '/PrefManager.php';

bool constructor Auth_PrefManager::Auth_PrefManager ( string $dsn , array $properties = NULL , string $defaultUser )

Description

The $properties property should be an associative array, with the structure below. Any options not set will be set to the default.

'table': The table to retrieve preferences from. [preferences]

'userColumn': The field to use for matching user IDs. [user_id]

'nameColumn': The field to use for matching preference names. [pref_name]

'valueColumn': The field to retrieve preference values from. [pref_value]

'defaultUser': The user ID to use for retrieving default values. [__default__]

'cacheName': The key to use for the cache in $_SESSION. [prefsCache]

'useCache': Should values be cached for later use. [true]

'serialize': Should values be serialized before saving to the database, and unserialized on retrieval. [false]

Parameter

string $dsn: The DSN of the database connection to make, or a DB object.

array $properties: An array of properties to set.

string $defaultUser: The default user to manage for.

Return value

returns Success or failure.

Throws

No exceptions thrown.

Note

This function can not be called statically.

Users with preferences created using Auth_PrefManager 1.0.4 or earlier shouldn't enable the serialize option, as it may result in data loss.

Auth_PrefManager::clearCache

Auth_PrefManager::clearCache() – Cleans out the cache.

Synopsis

require_once '/PrefManager.php';

void Auth_PrefManager::clearCache ( )

Description

Clears the cache of preferences stored in the current user's session.

Throws

No exceptions thrown.

Note

This function can not be called statically.

Auth_PrefManager::deleteDefaultPref

Auth_PrefManager::deleteDefaultPref() – Deletes a preference for the default user.

Synopsis

require_once '/PrefManager.php';

bool Auth_PrefManager::deleteDefaultPref ( string $pref_id )

Description

Deletes the default value for the preference passed as $pref_id.

Parameter

string $pref_id: The preference to delete.

Return value

returns Success/Failure

Throws

No exceptions thrown.

Note

This function can not be called statically.

Auth_PrefManager::deletePref

Auth_PrefManager::deletePref() – Deletes a preference for the specified user.

Synopsis

require_once '/PrefManager.php';

bool Auth_PrefManager::deletePref ( string $user_id , string $pref_id )

Description

Deletes the preference $pref_id for $user_id if one is set.

Parameter

string $user_id: The userid of the user to delete from.

string $pref_id: The preference to delete.

Return value

returns Success/Failure

Throws

No exceptions thrown.

Note

This function can not be called statically.

Auth_PrefManager::getDefaultPref

Auth_PrefManager::getDefaultPref() – Retrieves a default value.

Synopsis

require_once '/PrefManager.php';

mixed Auth_PrefManager::getDefaultPref ( string $pref_id )

Description

Retrieves the default value for $pref_id, even if there is currently a user ID set for the object being used.

Parameter

string $pref_id: The name of the preference to get.

Return value

returns The value if it's found, or NULL if it isn't.

Throws

No exceptions thrown.

Note

This function can not be called statically.

Auth_PrefManager::getPref

Auth_PrefManager::getPref() – Get a preference.

Synopsis

require_once '/PrefManager.php';

mixed Auth_PrefManager::getPref ( string $user_id , string $pref_id , bool $showDefaults = true )

Description

Retrieves the preference specified for a user, or, if returning default values is enabled, the default.

Parameter

string $user_id: The user to get the preference for.

string $pref_id: The preference to get.

boolean $showDefaults: Should default values be searched (overrides the global setting).

Return value

returns The value if it's found, or NULL if it isn't.

Throws

No exceptions thrown.

Note

This function can not be called statically.

Auth_PrefManager::setDefaultPref

Auth_PrefManager::setDefaultPref() – Set the default value for a preference.

Synopsis

require_once '/PrefManager.php';

bool Auth_PrefManager::setDefaultPref ( string $pref_id , mixed $value )

Description

Sets the default value for $pref_id, which will be retrieved if a user doesn't have the preference set.

Parameter

string $pref_id: The name of the preference to set.

mixed $value: The value to set it to.

Return value

returns Success or failure.

Throws

No exceptions thrown.

Note

This function can not be called statically.

Auth_PrefManager::setPref

Auth_PrefManager::setPref() – Set a preference.

Synopsis

require_once '/PrefManager.php';

bool Auth_PrefManager::setPref ( string $user_id , string $pref_id , mixed $value )

Description

Sets the value for $pref_id.

Parameter

string $user_id: The user to set for.

string $pref_id: The preference to set.

mixed $value: The value it should be set to.

Return value

returns Success or failure.

Throws

No exceptions thrown.

Note

This function can not be called statically.

Auth_PrefManager::setReturnDefaults

Auth_PrefManager::setReturnDefaults() – Set whether to return default values.

Synopsis

require_once '/PrefManager.php';

void Auth_PrefManager::setReturnDefaults ( mixed $returnDefaults = true )

Description

Set whether a default value should be returned by getPref() if no value was set for the specified user.

Parameter

mixed $returnDefaults

Throws

No exceptions thrown.

Note

This function can not be called statically.

getDefaultPref() will always return the default value.

Auth_PrefManager::useCache

Auth_PrefManager::useCache() – Sets whether the cache should be used.

Synopsis

require_once '/PrefManager.php';

void Auth_PrefManager::useCache ( bool $use = true )

Description

Sets whether the caching system should be used or not.

If the cache is enabled then any values retrieved will be saved in the user's session to reduce load on the database.

Parameter

boolean $use: Should the cache be used.

Throws

No exceptions thrown.

Note

This function can not be called statically.