view release on metacpan or  search on metacpan

lib/CGI/Builder/Auth/User.pm  view on Meta::CPAN

#---------------------------------------------------------------------
# Factory Methods
#---------------------------------------------------------------------
; sub list { $_[0]->_user_admin->list }

; sub add 
    { my ($self, $data) = @_
    ; my $username = delete $data->{'username'}
    ; my $password = delete $data->{'password'}

    ; return if $username eq 'anonymous'
    ; return if $self->_exists($username)
    
    ; $password = join(":",$username,$self->realm,$password)
        if $self->_user_admin->{ENCRYPT} eq 'MD5'

    ; return $self->_user_admin->add($username, $password, $data)
        ? $self->load(id => $username)
        : undef
    }

#---------------------------------------------------------------------
# Instance Methods
#---------------------------------------------------------------------
; sub _exists 
    { defined $_[1] 
        ? $_[0]->_user_admin->exists($_[1]) 
        : $_[0]->_user_admin->exists($_[0]->id) 
    }
; sub delete 
    { defined $_[1] 
        ? $_[0]->_user_admin->delete($_[1]) 
        : $_[0]->_user_admin->delete($_[0]->id) 
    }
; sub suspend 
    { defined $_[1] 
        ? $_[0]->_user_admin->suspend($_[1]) 
        : $_[0]->_user_admin->suspend($_[0]->id) 
    }
; sub unsuspend 
    { defined $_[1] 
        ? $_[0]->_user_admin->unsuspend($_[1]) 
        : $_[0]->_user_admin->unsuspend($_[0]->id) 
    }

; sub password_matches
    { my ($self, $passwd) = @_
    ; return unless $self->_exists
    ; $passwd = join(":",$self->id,$self->realm,$passwd)
        if $self->_user_admin->{ENCRYPT} eq 'MD5'
        
    ; my $stored_passwd = $self->_user_admin->password($self->id)
    ; return $self->_user_admin->{ENCRYPT} eq 'crypt'
        ? crypt($passwd,$stored_passwd) eq $stored_passwd
        : $self->_user_admin->encrypt($passwd) eq $stored_passwd
    }

; sub DESTROY
    { ref($_user_admin) 
            and !Scalar::Util::isweak($_user_admin) 
            and Scalar::Util::weaken($_user_admin)
    }

=head1 NAME

CGI::Builder::Auth::User - Provide access to a user table and its rows

=head1 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 L<context object|CGI::Builder::Auth::Context>
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.


=head1 SPECIAL PROPERTIES

The user object C<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 L<overload> for details.


=head1 CONSTRUCTORS


=head2 C<anonymous>

Class method, takes no arguments.

Return a user object with id of 'anonymous'. This user belongs to no groups.


=head2 C<load(id =E<gt> $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 C<$id>. Return C<undef> if the user
does not exist in the database. Attempts to C<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.