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!