/ 
Entities-0.5
River stage zero No dependents
/ Entities::User

NAME

Entities::User - A user entity that interacts with a web application.

VERSION

version 0.5

SYNOPSIS

used internally, see L<Entities>

DESCRIPTION

A user is an entity that interacts with your webapp. Generally, this is a human person that has signed up for your service, or was created by a customer, though it could be a privileged bot or whatever.

The user is that actual entity the performs actions on your webapp, and is thus required to be authorized to perform the actions they wish to perform. This is done either by assuming <roles|Entities::Role> or by explicitely being given <actions|Entities::Action>.

This entity class does the Abilities Moose role.

NOTE: you are not meant to create user objects directly, but only through the new_user() method in Entities.

METHODS

new( username => 'someguy', passphrase => 's3cr3t', [ realname => 'Some Guy', is_super => 0, roles => [], actions => [], customer => $customer_obj, id => 123, emails => [], created => $dt_obj, modified => $other_dt_obj, parent => $entities_obj ] )

Creates a new instance of this module. Only 'username' and 'passphrase' are required.

id()

Returns the ID of the user, if set.

has_id()

Returns a true value if the user object has an ID attribute.

_set_id( $id )

Sets the ID of the user object to the provided value. Only to be used internally.

username()

Returns the username of this user.

set_username( $name )

Changes the username of the user to the provided name.

realname()

Returns the real name of the user (i.e. person).

set_realname( $name )

Changes the real name of the user to the provided name.

passphrase()

Returns an MD5 digest of the passphrase set for this user.

set_passphrase( $new_passphrase )

Changes the passphrase of the user to the provided passphrase. Automatically created an MD5 digest of the passphrase, so do not pass a digested string here.

roles( [\@roles] )

In scalar context, returns an array-ref of all role names this user belongs to. In list context returns an array. If an array-ref of role names is provided, it will replace the current list.

has_roles()

Returns a true value if the user belongs to any role.

actions( [\@actions] )

In scalar context, returns an array-ref of all action names this user has been granted. In list context returns an array. If an array-ref of action names is provided, it will replace the current list.

has_actions()

Returns a true value if the user has beene explicitely granted any actions.

is_super()

Returns a true value if this user is a super-user. Super user can perform every possible action, in ANY SCOPE.

customer()

Returns the customer entity this user belongs to, if any.

has_customer()

Returns a true value if this user is a child of a customer entity.

emails( [\@emails] )

In scalar context, returns an array-ref of all email addresses set for this user. In list context returns an array. If an array-ref of email addresses is provided, it will replace the current list.

has_emails()

Returns a true value if the user has any emails assigned.

created()

Returns a DateTime object in the time the user object has been created.

modified( [$dt] )

Returns a DateTime object in the last time the object has been modified. If a DateTime object is provided, it is set as the new modified value.

parent()

Returns the Entities::Backend instance that stores this object.

add_to_role( $role_name )

Adds the user to role named $role_name. Croaks if such a role does not exist, warns if the user is already a member of this role. Returns the user object itself.

drop_role( $role_name )

Drops the assignment of the user to the role named $role_name. Warns if the user doesn't belong to this role, does not croak if the role does not even exist. Returns the user object itself.

grant_action( $action_name )

Grants the action named $action_name to the user. Croaks if this action does not exist, warns if the user has already been granted this action. Returns the user object itself.

has_direct_action( $action_name )

Returns a true value if the user has been explictely granted the action named $action_name (i.e. not via roles).

drop_action( $action_name )

Removes the action named $action_name from the list of actions the user has been explictely granted to perform. This doesn't necessarily mean the user will not be able to perform this action anymore, as it might be available to them via roles. Warns if the user wasn't granted this action, does not croak if the action does not exist. Returns the user object itself.

add_email( $email )

Adds the provided email address to the user's list of email addresses. Warns if the email is already assigned to this user. Does not (yet) check if the email is not assigned to any other user. Returns the user object itself.

has_email( $email )

Returns a true value if the user has the provided email.

drop_email( $email_address )

Removes the email address given from the user's list of email addresses. Warns if user doesn't have that address. Returns the user object itself.

get_role( $role_name )

Returns the role object of the role named $role_name.

METHOD MODIFIERS

The following list documents any method modifications performed through the magic of Moose.

around qw/roles actions emails/

If the roles(), actions() and emails() methods are called with no arguments and in list context - will automatically dereference the array-ref into arrays.

around BUILDARGS

Called before creating a new instance of Entities::User, this automatically turns the provided passphrase into an MD5 digest.

after anything_that_changes_object

Automatically saves the object to the backend after any method that changed it was executed. Also updates the 'modified' attribute with the current time before saving. Note, however, that the roles(), action() and emails() methods are not here, since they are only meant to be used for writing internally.

SEE ALSO

Entities.

AUTHOR

Ido Perlmuter, <ido at ido50 dot net>

BUGS

Please report any bugs or feature requests to bug-entities at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Entities. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

perldoc Entities

You can also look for information at:

LICENSE AND COPYRIGHT

Copyright 2010-2013 Ido Perlmuter.

This program is free software; you can redistribute it and/or modify it under the terms of either: the GNU General Public License as published by the Free Software Foundation; or the Artistic License.

See http://dev.perl.org/licenses/ for more information.