Apress
This article is an excerpt from Chapter 2 of Foundations of Pear, reprinted with permission from Apress.
Many Internet sites have at least some form of authentication, requiring a username and password that allows a user to be able to view content on the site or to post comments and edit content.
The authentication packages in this section provide a way of adding authentication and basic preference management to a site without you having to spend the time writing your own. After all, nearly all authentication is identical in its basic functionality, and there’s usually no good reason to spin off your own code if it’s already written for you.
The Auth package provides the base for authentication and allows you to store user information in a variety of different locations. The Auth package can use a database, a Simple Object Access Protocol (SOAP) call, or the traditional Unix-style passwd file.
The Auth_HTTP package provides a way for you to use HTTP standard challenges for authentication. Your web browser interprets the challenge from the server and shows an input box for the username and password. You might like this option if you don’t want to worry about writing your own HTML form to request the information.
The third and final package that’s discussed in this section is the Auth_PrefManager package. You can use this package to allow users to customize their experience with the site by storing user preferences. The examples of this behavior in this section are basic, but the projects at the end of this book dig deeper into using the Auth_PrefManager package.
Auth
You use the Auth package to authenticate users in your site. Out of the box, it supports many different ways of authenticating users, including storage in a database, in files, or even by using SOAP calls. You can even write a custom container object that allows you to write your own method to authenticate users.
Common Uses
The common uses of the Auth package include the following:
Related Packages
Dependencies
The Auth package depends on the packages listed here.

Required Packages

None

Optional Packages

AUTHENTICATION
Auth() Constructor
The constructor creates an instance of an Auth object.
void Auth(mixed $storageDriver [, mixed $options] [, string $loginFunction] [, boolean $showLogin = true])

Parameter Type Description
$storageDriver mixed This parameter can either be the name of the driver to use or
it can be a custom Auth_Container object.
$options mixed The options that are given for the provided storage driver.
$loginFunction string The name of the function that can be called to log in.
$showLogin boolean Determines whether or not to display the login page. Default
value is true.

addUser()
Adds a new user and returns true if the addition is successful. If the addition fails, the function will return AUTH_METHOD_NOT_SUPPORTED.
mixed addUser(string $username, string $password [mixed $additional = ""])

Parameter Type Description
$username string The name of the user that will be added to the storage
container. The storage container is the repository of user
information, such as a database or passwd file.
$password string The user’s password that will be added.
$additional mixed Additional options used by the storage container.

AUTHENTICATION
changePassword()
Changes the password for the given user and returns true if the change is successful. If the change fails, it will return AUTH_METHOD_NOT_SUPPORTED.

mixed changePassword(string $username, string $password)
Parameter Type Description
$username string The name of the user that is getting the password changed.
checkAuth()
Returns true if there is a session with valid authentication. boolean checkAuth()

getAuth()
Returns true if the current user is logged in. boolean getAuth()
getAuthData()
Returns the authentication data for the given field. If nothing is passed to the function, it will return everything that it knows about the current session.
mixed getAuthData([string $name = null])
Parameter Type Description
$name string The name of the field that contains the authentication data.
getPostPasswordField()
Returns the name of the field used for the password.
string getPostPasswordField()
getPostUsernameField()
Returns the name of the field used for the username.
string getPostUsernameField()

getStatus()
Returns the status of the current user.

string getStatus()

getUsername()
Returns the name of the current user.

string getUsername()

listUsers()
Returns an array containing the names of all the users in the current storage container.

array listUsers()

logout()
First calls the logout callback method, if one is defined, then sets the username and password to empty strings and sets the session to null.

void logout()

removeUser()
Deletes the given user from the storage container and returns true if the function is successful. If the user wasn’t deleted, the function returns AUTH_METHOD_NOT_SUPPORTED.

mixed removeUser(string $username)

Parameter Type Description

$username string The login name of the user to be removed.

sessionValidThru()
Returns the time in seconds until the session expires.

integer sessionValidThru()

setAdvancedSecurity()
If passed true, Auth begins to perform more advanced security checks, such as detecting IP address and user agent changes.

void setAdvancedSecurity([boolean $flag = true])

Join us next week as we continue this chapter on authentication!
This article is an excerpt from Chapter 2 of Foundations of Pear, reprinted with permission from Apress.