NAME

Krang::User - a means to access information on users

SYNOPSIS

  use Krang::ClassLoader 'User';

  # construct object
  my $user = Krang::User->new(email => 'a@b.com',               #optional
                              first_name => 'fname',            #optional
                              group_ids => [1, 2, 3],           #optional
                              last_name => 'lname',             #optional
                              login => 'login',                 #required
                              mobile_phone => '112-358-1321'    #optional
                              password => 'passwd',             #required
                              phone => '123-456-8901');         #optional

  # saves object to the DB
  $user->save();

  # getters
  ##########
  my $email     = $user->email();
  my $first_name= $user->first_name();
  my @group_ids = $user->group_ids();   # returns arrayref or array
  my $last_name = $user->last_name();
  my $login     = $user->login();
  my $password  = $user->password();
  my $phone     = $user->phone();

  my $id        = $user->user_id();     # undef until save()

  # setters
  ##########
  $user->first_name( 'first_name' );
  $user->group_ids( @ids );
  $user->last_name('last_name');
  $user->login( 'loginX' );
  $user->mobile_phone( $phone_number );
  $user->password( $password );         # stores MD5 of $self->SALT, $password
  $user->phone( $phone_number );

  # delete the user from the database
  $user->delete();

  # a hash of search parameters
  my %params =
  ( order_desc => 1,            # result ascend unless this flag is set
    limit => 5,                 # return 5 or less user objects
    offset => 1,                # start counting result from the
                                # second row
    order_by => 'user_id'       # sort on the 'user_id' field
    login_like => '%fred%',     # match rows with 'login's LIKE '%fred'
    phone_like => '718%' );     # match rows with phone#'s LIKE '718%'

  # any valid object field can be appended with '_like' to perform a
  # case-insensitive sub-string match on that field in the database

  # returns an array of user objects matching criteria in %params
  my @users = pkg('User')->find( %params );

DESCRIPTION

Each user object corresponds to an authorized user of the system. The degree of access a user is determined by the groups with which he is associated.

N.B. - Passwords are MD5 digests of $self->SALT and the password string; the original password string in not retrievable once it is passed but can only be calculated and compared i.e.:

  my $valid_password =
    $user->{password} eq md5_hex($self->SALT, $password_string) ? 1 : 0;

INTERFACE

FIELDS

Access to fields for this object is provided my Krang::MethodMaker. The value of fields can be obtained and set in the following fashion:

 $value = $user->field_name();
 $user->field_name( $some_value );

The available fields for a user object are:

• email
  
• first_name
  
• group_ids
  
All the list utility methods provided by Class::MethodMaker are also available for this field see Class::MethodMaker
• last_name
  
• login
  
• mobile_phone
  
• password
  
• phone
  
• user_id (read-only)
  
The id of the current object in the database's user table
• user_uuid (read-only)
  
A unique id of the current object valid between systems when the object is moved via krang_export/krang_import.

METHODS

• $user = Krang::User->new( %params )
  
Constructor for the module that relies on Krang::MethodMaker. Validation of '%params' is performed in init(). The valid fields for the hash are:
• email
  
• first_name
  
• group_ids
  
• last_name
  
• login
  
• mobile_phone
  
• password
  
• phone
  
• $user_id = Krang::User->check_auth( $login, $password )
  
Class method that retrieves the user object associated with $login and compares the value in the objects 'password' field with md5_hex( $self->SALT, $password ). If it is successful, the 'user_id' is returned, otherwise '0' is returned.
• $match = $user->check_pass( $password )
  
• $success = $user->delete()
  
• $success = Krang::user->delete( $user_id )
  
Instance or class method that deletes the given user object from the database. It returns '1' following a successful deletion.

N.B. - this call may result in an exception as it precipitates a call to dependent check. See $user->dependent_check().

• $user->dependent_check()
  
This method checks whether an objects are checked out by the current user. If this is the case a Krang::User::Dependency exception is thrown. Krang::User::Dependency exceptions contain a 'dependencies' field that contains a hash of class names and id of that class that depend on this User object. One can handle such an exception thusly:

 eval {$user->dependent_check()};
 if ($@ && $@->isa('Krang::User::Dependency')) {
     my %dependencies = $@->dependencies;
     croak("The following objects depend on this user:\n\t" .
           join("\n\t", map {"$_: " . join(",", @{$dependencies{$_}})}
                keys %dependencies));
 }

• dependent_class_list
  
Returns a list of classes to check for potential objects that could be checked-out by users. This is called by dependent_check() and mainly exists to be overridden by addons.

Classes in this list must implement the find() and id_meth() methods.

• $user->duplicate_check()
  
This method checks the database to see if any existing site objects possess any of the same values as the one in memory. If this is the case, a Krang::User::Duplicate exception is throw; otherwise, 0 and undef are returned.

Krang::User::Duplicate exception have a 'duplicates' field that contains info about the object that would be duplicated. One can handle the exception thusly:

 eval {$user->duplicate_check()};
 if ($@ && $@->isa('Krang::User::Duplicate')) {
     my %duplicates = $@->duplicates;
     croak("The following objects are duplicated on this object:\n\t" .
           join("\n\t", map {"$_: " . join(",", @{$duplicates{$_}})}
                keys %duplicates));
 }

• @users = Krang::User->find( %params )
  
• @users = Krang::User->find( user_id => [1, 1, 2, 3, 5] )
  
• @users = Krang::User->find( group_ids => [1, 1, 2, 3, 5] )
  
• @user_ids = Krang::User->find( ids_only => 1, %params )
  
• $count = Krang::User->find( count => 1, %params )
  
Class method that returns an array of user objects, user ids, or a count. Case-insensitive sub-string matching can be performed on any valid field by passing an argument like: ``fieldname_like => '%$string%''' (Note: '%' characters must surround the sub-striqng). The valid search fields are:
• login
  
• email
  
• first_name
  
• group_id
  
• last_name
  
• login
  
• mobile_phone
  
• phone
  
• user_id
  
• user_uuid
  
• simple_search
  
Searches first_name, last_name and login for matching LIKE strings

Additional criteria which affect the search results are:

• ascend
  
Result set is sorted in ascending order.
• count
  
If this argument is specified, the method will return a count of the categories matching the other search criteria provided.
• ids_only
  
Returns only user ids for the results found in the DB, not objects.
• limit
  
Specify this argument to determine the maximum amount of user objects or user ids to be returned.
• offset
  
Sets the offset from the first row of the results to return.
• order_by
  
Specify the field by means of which the results will be sorted. By default results are sorted with the 'user_id' field.
• order_desc
  
Set this flag to '1' to sort results relative to the 'order_by' field in descending order, by default results sort in ascending order

The method croaks if an invalid search criteria is provided or if both the 'count' and 'ids_only' options are specified.

• $md5_digest = $user->password()
  
• $md5_digest = $user->password( $password )
  
• $md5_digest = Krang::User->password( $password )
  
• $md5_digest = Krang::User->password( $password, 1 )
  
Method to get or set the password associated with a user object. Returns Digest::MD5->md5( $self->SALT . $password_string ) as a getter. Stores the same in the DB as a setter. As a class method it returns an md5 digest of its argument. If a true argument is passed in after the first 'password' arg, the password is not encrypted (assumed to be already).
• $user = $user->save()
  
Saves the contents of the user object in memory to the database. 'user_id' will be defined if the call is successful.

The method croaks if the save would result in a duplicate object (i.e. if any field value required to be unique is not found to be so). It also croaks if its database query affects no rows in the database.

• $user->serialize_xml(writer => $writer, set => $set)
  
Serialize as XML. See Krang::DataSet for details.
• $user = Krang::User->deserialize_xml(xml => $xml, set => $set, no_update => 0)
  
Deserialize XML. See Krang::DataSet for details.

If an incoming user has the same login as an existing user then an update will occur, unless no_update is set.

• $user->may_delete_user($other_user_obj)
  
• $user->may_delete_user($other_user_id)
  
Convenience method accepting a Krang::User object or a user id. Returns true if the calling user may delete the given user, false otherwise. This method may be used in Krang::CGI::User to prevent CGI param tampering.
• $current_user = pkg('User')->current_user_group_ids
  
• $current_user = $other_user->current_user_group_ids
  
Convenience method returning the group_ids for the logged in user.

TO DO

SEE ALSO

Krang, Krang::DB