The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
OpenInteract-1.99_05
River stage zero No dependents
1 ++
/ OpenInteract2::Auth::User

NAME

OpenInteract2::Auth::User - Base class for creating OpenInteract users

SYNOPSIS

 # Called by OI2::Auth
 
 my ( $user, $is_logged_in ) =
     OpenInteract2::Auth::User->get_user( $auth );
 print "User ", $user->login_name, " logged in? ", $is_logged_in, "\n";
 print "User ", $auth->user->login_name, " logged in? ", $auth->is_logged_in, "\n";

DESCRIPTION

Handles retrieving a user object. If no user is logged in should still return a user object, just one that isn't persisted to a database.

METHODS

Public Interface

get_user( $auth )

Given $auth (an OpenInteract2::Auth object), returns a user and a flag indicating whether the user is logged in. Here's the process it uses:

  • It first checks a cache (calling _get_cached_user()), which generally means the session. You control whether the user object is cached in the session with the 'session_info.cache_user' key.

    If a user is found in the cache we set the 'logged-in' flag set to true.

  • If no user is found in the cache it checks for a user ID (calling _get_user_id()).

  • If a user ID is found it tries to fetch the user matching it (calling _fetch_user()). If that fetch fails we call _fetch_user_failed(), passing along the user ID we tried to fetch and an error message.

  • If the fetch succeeds we call _check_first_login() with the user object to run any initialization routines and then _set_cached_user() with the user object so that it may be cached if necessary. We also flip the 'logged-in' flag to true.

At this point if we have a user object we return it with the 'logged-in' flag.

  • Next we try to fetch the user information from the request input. This maps to someone logging in using a GET/POST form.

  • If we find the user from the request input we pass the user to each of the following calls: _check_first_login() (same as above), _remember_login() (sets a flag for the session to pickup whether the session is transient or permanent) and _set_cached_user() (same as above). We also flip the 'logged-in' flag.

  • If we don't find the user from the request input we call _create_nologin_user() to return a transient user object; we also set the 'logged-in' flag to false.

Finally we return the user object and logged-in flag. These are also set in the $auth object.

Overridable Methods

The following methods are overridable by subclasses. Mix and match however you like.

_get_cached_user()

Retrieves the user from a cache. By default this looks in the session, but you can use other means.

Returns: two-item list, user object and user ID.

_set_cached_user( $user )

If a cache is configured saves $user there. Otherwise does nothing.

_get_user_id()

Returns the user ID associated with this session.

_fetch_user( $user_id )

Retrieves the user from permanent storage matching ID $user_id. If the operation fails it should throw an exception.

_fetch_user_failed( $user_id, $error_msg )

Called when _fetch_user() throws an exception or fails to return a user.

_login_user_from_input()

Finds the username from the request field specified in 'login.login_field' and the password from 'login.password_field' and tries to fetch a user by the name and log her in.

If a user is found and authenticated, return the user object. Otherwise return undef.

_check_first_login( $user )

See if $user has logged in for the first time and perform any necessary actions.

_remember_login( $user )

If the value for the request field specified in 'login.remember_field' is set to true then we 'remember' the user by default. This generally means the session won't expire when the user closes her browser.

_create_nologin_user()

Return a transient user object. This object should normally not be saved to the database but created on the fly with a known username and ID. The ID of the theme should be set to 'default_objects.theme'.

COPYRIGHT

Copyright (c) 2002-2004 Chris Winters. All rights reserved.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

AUTHORS

Chris Winters <chris@cwinters.com>