NAME
CGI::Builder::Auth::User - Provide access to a user table and its rows
DESCRIPTION
This Class provides an API for manipulating a User table. The implementation stores the table in a text file, but developers are free to create their own implementations of this API that wrap SQL databases or other resources.
Developers using the library probably will not need to manipulate the user objects directly, since the context object provides a wrapper around all the common functions. However, developers creating their own user classes need to pay special attention to implementing this API correctly.
This document describes the default implementation, and includes many notes about mandatory and optional features for alternate implementations.
WARNING: This interface is experimental. Developers may create their own implementations, but are advised to subscribe to the mailing list to be notified of changes. Backward compatibility is a goal, but is not guaranteed for future releases.
SPECIAL PROPERTIES
The user object overload's the string operator so that prints the username in string context rather than the usual reference information. As a result, you may use the user object in your code as if it were a (read-only) scalar containing the username.
This is required behavior for all implementations. See overload for details.
CONSTRUCTORS
anonymous
Class method, takes no arguments.
Return a user object with id of 'anonymous'. This user belongs to no groups.
load(id => $id)
Class method, takes a hash where the key is 'id' (literal) and the value is the username you wish to load.
Return a user object with the username of $id. Return undef if the user does not exist in the database. Attempts to load a user with id of 'anonymous' must always fail, this username is reserved. To construct an anonymous user, call the 'anonymous' constructor instead.
Note that the username is required to be unique in a given table.
add(\%attr)
Add a user to the user table.
Class method, takes a reference to a hash of user attributes. Attributes supported in this implementation:
- username
- password
All implementations are required to support these two attributes, and may support as many more as they like. Note that the username is required to be unique in a given table.
Return the user object on success, undef on failure.
OTHER CLASS METHODS
config([$opt[,$new_val]])
Class method, takes one or two scalar arguments.
Store and retrieve configuration options. With one argument $opt, returns the value of the config option. With two arguments, stores $new_val as the new value for config option $opt. Returns undef if the option is unset.
list
Class method, takes no arguments.
Return an array of all users (as objects) in the user table, or undef on error.
INSTANCE (OBJECT) METHODS
delete
Instance method, takes no arguments.
Delete the user from the user table. After a call to this method, the object should be considered unusable. (In practice this implementation makes the object anonymous, but this behavior is not required and is not guaranteed to be true in future releases. Do not rely on it.)
password_matches($password)
Instance method, takes one scalar argument, a string.
Return true if the $password argument matches the password stored in the table. This allows the storage class to implement its own one-way hash function to obscure the password in storage if desired. Note that the user object is never required to return the stored password, but implementations may allow this if desired.
suspend
Instance method, takes no arguments.
Places this user in a suspended status. When suspended, the user method password_matches always returns false.
This method is not currently used by the Context object, but support will be added in a (near) future release. Therefore, implementations are required to support this method.
unsuspend
Instance method, takes no arguments.
Removes this user from suspended status. When suspended, the user method password_matches always returns false.
This method is not currently used by the Context object, but support will be added in a (near) future release. Therefore, implementations are required to support this method.
SUPPORT
Support for this module and all the modules of the CBF is via the mailing list. The list is used for general support on the use of the CBF, announcements, bug reports, patches, suggestions for improvements or new features. The API to the CBF is stable, but if you use the CBF in a production environment, it's probably a good idea to keep a watch on the list.
You can join the CBF mailing list at this url:
http://lists.sourceforge.net/lists/listinfo/cgi-builder-users
AUTHOR
Vincent Veselosky
COPYRIGHT AND LICENSE
Copyright 2004 by Vincent Veselosky
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.