Onwards and Upwards

In the first part of this article, I focused almost entirely on how patUser
could simplify the task of adding authentication to your site. I explained the
patUser database schema, ran you through the process of initializing a patUser
object instance and linking it to a database and template engine, and showed
you how built-in patUser methods could simplify the task of verifying user
credentials and writing login and logout scripts.

However, patUser can do a lot more than just handle user authentication - the
library also comes with a large number of methods designed to make the task of
managing user data as simple and efficient as possible. Over the course of
this second installment, I'm going to show you how these methods work, and how
they can be used to quickly create scripts to view, add, edit and delete users
(and user attributes) from your database. Keep reading!

Meeting The Family

Let's start with the basics - obtaining a list of current users from the
database. If you've been following along, you already know that right now, the
database has only a single user, "joe". Let's add a couple more:

You can verify the result with a quick SQL query to the "users" table:

Now, let's try doing the same with patUser:

The first part of this script should be easily recognizable to you by now - it consists of the code needed to instantiate a patUser object instance and prepare it for use. Once the object has been prepared, the getUsers() function is used to retrieve a list of all the users in the database. The return value of the getUsers() method is an associative array containing user records, one element for each record.

The first argument to the getUsers() function is an array containing the names of the fields to be included in the result set - these field names appear as keys in the returned array, and can be used to access the corresponding values. Here's the output:

You're not restricted to using just the default fields built into the patUser database schema - you can just as easily add your own. Find out how, on the next page.

Asking For More

Now, let's make some additions to the patUser-provided schema for the "users" table. You might remember that the original schema looked like this:

Let's alter this to include some additional fields, for age, sex and telephone number:

While we're at it, let's also insert a few records into the new table:

As before, I can retrieve this information via an SQL query,

or have patUser do it for me via its getUsers() function:

In this case, I've told getUsers() to retrieve a few extra fields from the database - specifically, the "age", "sex" and "tel" fields. You'll remember these are not standard patUser fields, but have been added by me for illustrative purposes.

Here's the output:

Drilling Deeper

You can also get fancy by adding selection criteria in your call to getUsers(), as a second argument to the method. Consider the following variant of the example above, which only returns records of those users who are male and between 18 and 25:

In this case, the second argument to the getUsers() method - a series of nested arrays containing selection criteria - provides patUser with a list of additional conditions to be satisfied when querying the database. Only those user records that match the specified conditions will be included in the result.

Here's the output:

All For One, And One For All

patUser also allows you to organize users into named collections or groups. You might remember, from the discussion of the patUser database schema in the previous segment of this article, that there are two tables designed specifically for this task, the "groups" table (which maintains a list of available groups) and the "usergroups" table (which maintains a list of which users belong to which group).

Here's the schema for the "groups" tables:

Let's now add a couple of groups to the system,

and verify that they have been added correctly via an SQL query:

Obviously, we can perform the same task using patUser's getGroups() function, which works in much the same way as the getUsers() function discussed on the previous page. The following code listing demonstrates:

Here's the output:

Note the introduction of a new method in the script above, setGroupTable(). This method, together with the setGroupFields()method, allows you to configure patUser to use a different set of tables than its default by remapping the default table and column references to custom values.

Accounting For Change

The default patUser-supplied database schema for the "groups" table includes only two group attributes: its name, and a unique group ID. Most of the time, this is sufficient; however, in case you need to add more attributes, patUser can be easily tweaked to work with this extra data.

Let's alter the default "groups" table to include some additional fields, for description and location:

While we're at it, let's also insert a few records into the new table:

As before, I can retrieve this information via an SQL query,

or have patUser do it for me via its getGroups() function:

California Calling

You can also apply selection criteria in your call to getGroups(), so as to return only a specific subset of records. Consider the following variant of the example above, which only returns those groups located in California:

Here's the output:

Making New Friends

It's just as simple to add new users and groups to the system - all you need to do is use patUser's addUser() and addGroup() methods, which accept an array of field-value pairs and uses them to create a new user or group record in the database. Both methods return the ID of the newly-created user or group if successful. Consider the following example, which demonstrates how to add new users:

By default, patUser automatically logs the newly-created user into the system. You can avoid this by specifying a second argument to addUser(), as in the example below:

In a similar manner, a new group may be added - here's how:

A Fast Edit

Once a user is entered into the system, patUser allows you to add new data to the user record, or make changes to the existing data, with its modifyUser() method. This method accepts two primary arguments: an array containing the data to be inserted, and an array containing the user ID of the record to edited and related options.

Consider the following example, which illustrates the process of editing a user record and entering new information into it:

Note that in the example above, all changes will be made to the record with user ID 15. If no user ID is provided, the currently logged-in user's ID is used instead.

You can also modify group data with the corresponding modifyGroup() method. I'll leave that to you to experiment with.

Here Today, Gone Tomorrow

Just as you can add and edit users, patUser() also comes with - obviously! - a deleteUser() method. This method accepts, as input, a user ID, and removes the corresponding user record from the database. If no user ID is provided, the currently logged-in user's ID is used instead. The following example demonstrates:

Similarly, the deleteGroup() method allows you to remove a group from the group database.

Connecting The Dots

Once you've got your users and groups created, you can begin organizing users into groups, via the addUserToGroup() and removeUserFromGroup() methods.

Given the following users and groups,

it's fairly easy to, say, add "joe" and "sarah" to the "Accounts" and "Operations" group,

or remove "sarah" from "Operations" and move her into "Human Reources".

Once you've got your users organized the way you want them, patUser also offers the following three utility functions to help you make sense of all the relationships:

getJoinedGroups() - returns a list of the groups the named user belongs to, accepts user ID as input

getUsersInGroup() - returns a list of all the users in a named group, accepts group ID and list of required user attributes as input

isMemberOfGroup() - returns a Boolean value indicating whether or not the named user belongs to the named group, accepts user ID and group ID as input

The following example illustrates how these work:

Here's the output:

Needless to say, these utility functions come in very handy when you need to find out which users belong to which groups, or if you need to alter the various user and group configurations. You'll see this in action in the composite example on the next page.

A Well-Formed Plan

Now, how about a couple of examples to put all this in context? This first example demonstrates how the various user and group manipulation methods discussed in this article can be used to rapidly build a user administration module for a Web application or Web site. Consider the following script, which is designed to allow administrators to add new users to the system.