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>