User Authentication with patUser (part 1) - Icing On The Cake
( Page 7 of 7 )

In case your application database schema is already designed and integrating the patUser schema into it would lead to redundancies or complications, you can configure patUser to use a different set of tables than its default. This is accomplished by means of the setAuthTables() and setAuthFields() methods, which allow you to remap patUser's default table and column references to custom values of your own.

In order to better understand this, consider the following table, which contains user authentication information:

CREATE TABLE zx_users (
  uid int(10) unsigned NOT NULL auto_increment,
  uname varchar(20) NOT NULL default '',
  upswd varchar(20) NOT NULL default '',
  PRIMARY KEY  (uid)
) TYPE=MyISAM;

Now, while this table contains a subset of the information in patUser's "users" table, it does not have the same table and column names. I can, however, still integrate it with patUser, simply by remapping patUser to use the new table and columns. The following example demonstrates:

<?php

// include classes
include("../include/patDbc.php"); include("../include/patUser.php");
include("../include/patTemplate.php");

// initialize database layer
$db = new patMySqlDbc("localhost", "db211", "us111", "secret");

// initialize template engine
$tmpl = new patTemplate();
$tmpl->setBasedir("../templates");

// initialize patUser
$u = new patUser(true);

// connect patUser to database/template engines $u->setAuthDbc($db);
$u->setTemplate($tmpl);

// tell patUser where to get user information from
$u->setAuthTable("zx_users"); $u->setAuthFields( array(
	"uid" => "uid", 
	"username" => "uname",
	"passwd" => "upswd"
));

// check credentials before displaying page
$uid = $u->requireAuthentication("displayLogin");

// restricted page goes here

?>

As you can see, I've told patUser where to find the data by remapping the old column names to the ones in the new table.

Though the requireAuthentication() method displays a login box by default, this default behaviour can be altered by passing a different argument to the method. If, instead of displaying a login box, you would simply like a blank screen to be displayed when an unauthenticated user arrives at the page, you can use the following code:

<?php

$u->requireAuthentication("exit");

?>

As you might imagine, the "exit" argument tells the requireAuthentication() method to simply exit without displaying a login box. The end result? Users without appropriate authentication credentials will see an empty page.

The return value of the requireAuthentication() method is a user ID (if the authentication is successful) or false (if it isn't); this user ID may then be used in subsequent PHP code. patUser also provides a getUid() method, which can be used at any time to retrieve the currently logged-in user's ID (you'll see this in action in subsequent examples).{mospagebreak title=Making A Graceful Exit} You can also use the isAuthenticated() utility function to check if a user is authenticated, as demonstrated below:

<?php

// include classes
include("../include/patUser.php");

// initialize patUser
$u = new patUser(true);

if ($u->isAuthenticated())
{
	echo "Welcome!";

	// or you could display the page
}
else
{
	echo "Leave now or I'll make you!";

	// or you could redirect the user to an error page
}

?>

You can also restrict the maximum number of login attempts with the setMaxLoginAttempts() method. Once that maximum number is reached, patUser will automatically display the contents of the template "patUserUnauthorized.tmpl", or you can redirect the user to a new URL, which you can set with the setUnauthorizedUrl() method.

Finally, now that you know how to handle logging in, how about logging out? Well, it's equally simple - patUser provides a logOut() method, which terminates the user's session and destroys all related user information. Consider the following example, which illustrates:

<?php

// include class
include("../include/patUser.php");

// initialize patUser
$u = new patUser(true);

// log out
$u->logOut();

// redirect to index page
header("Location: index.php");

?>

That's about all for the moment. In this article, I discussed the patUser class, explaining some of its methods and illustrating how they could be used in the context of a Web application to authenticate and verify user credentials. I showed you how Web pages could be secured by the simple addition of a single method call, how to modify patUser so it fits into your application's overall look and feel, and how to integrate a custom database schema into the patUser world.

Thus far, I've been assuming the existence of a correctly filled-in database for patUser to use, without wondering too much about how that database was created or maintained. In the second part of this article, those items will come to the fore, when I discuss built-in patUser functions to retrieve user data; add, modify and delete users and user information; organize users into groups; and manager user and group relationships. Make sure you come back for that one!

Note: Examples are illustrative only, and are not meant for a production environment. Melonfire provides no warranties or support for the source code described in this article. YMMV!

>>> More PHP Articles          >>> More By icarus, (c) Melonfire