/ 
Class-User-DBI-0.10
River stage zero No dependents
/ Class::User::DBI::Userdomains

NAME

Class::User::DBI::UserDomains - A user user domains class.

VERSION

Version 0.10

SYNOPSIS

Through a DBIx::Connector object, this module models a class of domains belonging to a user.

# Set up a connection using DBIx::Connector:
# MySQL database settings:

my $conn = DBIx::Connector->new(
    'dbi:mysql:database=cudbi_tests, 'testing_user', 'testers_pass',
    {
        RaiseError => 1,
        AutoCommit => 1,
    }
);


# Now we can play with Class::User::DBI::UserDomains

# Set up a 'user-domains' table in the database.
Class::User::DBI::UserDomains->configure_db( $conn );

# Instantiate a UserDomains object so we can play with it.
my $ud = Class::User::DBI::Domains->new( $conn, 'userid' );

$ud->add_domains( 'Treasure Island', 'Nimh' ); # This user works with TI and Nimh.

print "This user works with Nimh.\n" if $ud->has_domain( 'Nimh' );

my @domains = $ud->fetch_domains;
foreach my $domain ( @domains ) {
    print "This user works with $domain\n";
}

$ud->delete_domains( 'Treasure Island' ); # Pass a list for multiple deletes.

DESCRIPTION

This is a maintenance class facilitating the creation, deletion, and testing of domains belonging to a user.

Before a domain may be granted to a user with this class, you need to create a domain entry using Class::User::DBI::Domains. That class manages domains and their description. This class grants those domains to a user. Please refer to the documentation for Class::User::DBI::Domains to familiarize yourself with adding domains to the system.

A common usage is to configure a 'cud_userdomains' database table, and then add one or more user => domain pairs. Domains are locality jurisdictions that a given user may have. Using Class::User::DBI you have set up a set of users. Using Class::User::DBI::Domains you have set up a list of domains and their descriptions. Now this class allows you to assign one or more of those domains to a user.

Finally, the user object may be queried to determine if a user has a given domain.

Domains are intended to be used independently of Roles and Privileges. The idea is that a user has a Role which gives him Privileges that may be exercised within his domain. But at the lowest level, a domain is just another set of flags that a user may hold, which can be used any way you want. I tend to think of them as constraints on where a privilege may be applied.

An example is that a user who has a 'sales' role might have a 'sales reports' privilege. But the 'West Coast' domain could be used to constrain this user to only manipulating sales reporting that pertains to the West Coast locality.

On the other hand, another user is a sales manager, and has both the West Coast and the East Coast under her jurisdiction. Her 'manager' role may still give her the 'sales reports' privilege, but she will have two domains: West Coast and East Coast, thereby having access to sales reports resources for both of those domains.

EXPORT

Nothing is exported. There are many object methods, and three class methods, described in the next section.

SUBROUTINES/METHODS

new (The constructor -- Class method.)

my $user_domain_obj = Class::User::DBI::UserDomains->new( $connector, $role );

Creates a user-domains object that can be manipulated to set and get domains for the instantiated user. These user/domain pairs will be stored in a database table named cud_userdomains. Throws an exception if it doesn't get a valid DBIx::Connector or a valid userid (where valid means the userid exists in the users table managed by Class::User::DBI.

configure_db (Class method)

Class::User::DBI::UserDomains->configure_db( $connector );

This is a class method. Pass a valid DBIx::Connector as a parameter. Builds a minimal database table in support of the Class::User::DBI::UserDomains class.

The table created will be cud_userdomains.

add_domains

$ud->add_domains( 'Mississippi', 'Milwaukee', ... );

Add one or more domains. Each domain must match a domain that lives in the domains database, managed by Class::User::DBI::Domains.

It will drop requests to add domains that already exist for a given user.

Returns a count of domains added, which may be less than the number passed if one already existed.

delete_domains

$ud->delete_domains( 'California', 'Florida' ); # No more sunny beaches.

Deletes from the user all domains specified. Return value is the number of domains actually deleted, which may be less than the number of domains requested if any of the requested domains don't exist for the object's target user.

has_domain

print "This user gets to enjoy the surf." 
    if $ud->has_domain( 'Hawaii' );

Returns true if a given domain exists for the object's target user, and false if not.

fetch_domains

foreach my $domain ( $ud->fetch_domains ) {
    print "This user works with $domain\n";
}

Returns a list of domains belonging to the object's target user.

An empty list means there are no domains defined for this user.

get_userid

my $userid = $ud->get_userid;

Just an accessor for reading the object's target user ID.

DEPENDENCIES

The dependencies for this module are the same as for Class::User::DBI, from this same distribution. Refer to the documentation in that module for a full description.

CONFIGURATION AND ENVIRONMENT

Please refer to the configure_db() class method for this module for a simple means of creating the table that supports this class.

All SQL for this distribution is contained in the Class::User::DBI::DB module.

DIAGNOSTICS

If you find that your particular database engine is not playing nicely with the test suite from this module, it may be necessary to provide the database login credentials for a test database using the same engine that your application will actually be using. You may do this by setting $ENV{CUDBI_TEST_DSN}, $ENV{CUDBI_TEST_DATABASE}, $ENV{CUDBI_TEST_USER}, and $ENV{CUDBI_TEST_PASS}.

Currently the test suite tests against a SQLite database since it's such a lightweight dependency for the testing. The author also uses this module with several MySQL databases. As you're configuring your database, providing its credentials to the tests and running the test scripts will offer really good diagnostics if some aspect of your database tables proves to be at odds with what this module needs.

INCOMPATIBILITIES

This module has only been tested on MySQL and SQLite database engines. If you are successful in using it with other engines, please send me an email detailing any additional configuration changes you had to make so that I can document the compatibility, and improve the documentation for the configuration process.

BUGS AND LIMITATIONS

Let me know if you find any!

AUTHOR

David Oswald, <davido at cpan.org>

BUGS

Please report any bugs or feature requests to bug-class-user-dbi at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Class-User-DBI. 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 Class::User::DBI::UserDomains

You can also look for information at:

ACKNOWLEDGEMENTS

LICENSE AND COPYRIGHT

Copyright 2012 David Oswald.

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.